Utilities

bbox

class osdatahub.bbox.BBox(west: float, south: float, east: float, north: float)

Bases: object

BBox is a dataclass that specifies a rectangular polygon made up of north, south, east and west. It is indiscriminate of CRS and so is used as part of the more comprehensive Extent class

east: float

north: float

south: float

to_string(precision: Optional[int] = None) → str

Converts bounding box into string

Parameters: precision (int) – Decimal point rounding precision. Defaults to None (no rounding)
Returns: bounding box in string form
Return type: str

west: float

errors

osdatahub.errors.raise_http_error(response)

filters

class osdatahub.filters.Filter(xml: str)

Bases: object

A container class for an OGD XML filter. Allows XML to be joined using and and or operations. It should not be instantiated directly, instead produced by one of the methods in this module.

osdatahub.filters.contains(extent: osdatahub.extent.Extent) → osdatahub.filters.Filter

Constructs an OGC XML filter for data that contains the given extent

Parameters: extent (Extent) – The desired region to be filtered, given as an Extent object
Returns: A valid OGC XML filter
Return type: Filter

osdatahub.filters.crosses(extent: osdatahub.extent.Extent) → osdatahub.filters.Filter

Constructs an OGC XML filter for data that crosses the given extent

Parameters: extent (Extent) – The desired region to be filtered, given as an Extent object
Returns: A valid OGC XML filter
Return type: Filter

osdatahub.filters.disjoint(extent: osdatahub.extent.Extent) → osdatahub.filters.Filter

Constructs an OGC XML filter for data that does not interact with the given extent

Parameters: extent (Extent) – The desired region to be filtered, given as an Extent object
Returns: A valid OGC XML filter
Return type: Filter

osdatahub.filters.equals(extent: osdatahub.extent.Extent) → osdatahub.filters.Filter

Constructs an OGC XML filter for data that is equal to the given extent

Parameters: extent (Extent) – The desired region to be filtered, given as an Extent object
Returns: A valid OGC XML filter
Return type: Filter

osdatahub.filters.filter_and(*filters: osdatahub.filters.Filter) → osdatahub.filters.Filter

Constructs an OGC XML filter that performs an ‘and’ on the given filters

Parameters: filters (Filter) – The filters to be joined
Returns: A valid OGC XML filter
Return type: Filter

osdatahub.filters.filter_or(*filters: osdatahub.filters.Filter) → osdatahub.filters.Filter

Constructs an OGC XML filter that performs an ‘or’ on the given filters

Parameters: filters (Filter) – The filters to be joined
Returns: A valid OGC XML filter
Return type: Filter

osdatahub.filters.intersects(extent: osdatahub.extent.Extent) → osdatahub.filters.Filter

Constructs an OGC XML filter for data that intersects the given extent

Parameters: extent (Extent) – The desired region to be filtered, given as an Extent object
Returns: A valid OGC XML filter
Return type: Filter

osdatahub.filters.is_between(property_name: str, lower: float, upper: float) → osdatahub.filters.Filter

Constructs an OGC XML filter for a numerical attribute between 2 values

Parameters

property_name (str) – Property / attribute name to be filtered
lower (float) – The filter’s lower bound
upper (float) – The filter’s upper bound

Returns

A valid OGC XML filter

Return type

Filter

osdatahub.filters.is_equal(property_name: str, value: Union[str, float]) → osdatahub.filters.Filter

Constructs an OGC Filter for an attribute that is equal to the input value

Parameters

property_name (str) – Property / attribute name to be filtered
value (Union[str, float]) – Value used in filter for comparison

Returns

A valid OGC XML filter

Return type

Filter

osdatahub.filters.is_greater_than(property_name: str, value: float) → osdatahub.filters.Filter

Constructs an OGC Filter for a numerical attribute that is greater than the input value

Parameters

property_name (str) – Property / attribute name to be filtered
value (float) – Value used in filter for comparison

Returns

A valid OGC XML filter

Return type

Filter

osdatahub.filters.is_greater_than_or_equal_to(property_name: str, value: float) → osdatahub.filters.Filter

Constructs an OGC Filter for a numerical attribute that is greater than or equal to the input value

Parameters

property_name (str) – Property / attribute name to be filtered
value (float) – Value used in filter for comparison

Returns

A valid OGC XML filter

Return type

Filter

osdatahub.filters.is_less_than(property_name: str, value: float) → osdatahub.filters.Filter

Constructs an OGC Filter for a numerical attribute that is less than the input value

Parameters

property_name (str) – Property / attribute name to be filtered
value (float) – Value used in filter for comparison

Returns

A valid OGC XML filter

Return type

Filter

osdatahub.filters.is_less_than_or_equal_to(property_name: str, value: float) → osdatahub.filters.Filter

Constructs an OGC Filter for a numerical attribute that is less than or equal to the input value

Parameters

property_name (str) – Property / attribute name to be filtered
value (float) – Value used in filter for comparison

Returns

A valid OGC XML filter

Return type

Filter

osdatahub.filters.is_like(property_name: str, value: str, wildcard: str = '*', single_char: str = '#', escape_char: str = '!') → osdatahub.filters.Filter

Constructs an OGC XML filter for a string attribute that is similar to the input value

Parameters

property_name (str) – Property / attribute name to be filtered
value (str) – String that is used to match with attribute values
wildcard (str, optional) – A character that any combination of other characters will match with. Defaults to “*”.
single_char (str, optional) – A character that any single character will match with. Defaults to “#”.
escape_char (str, optional) – Used to escape the meaning of the wildcard, single_char and escape_char itself. Defaults to “!”.

Returns

A valid OGC XML filter

Return type

Filter

osdatahub.filters.is_not_equal(property_name: str, value: Union[str, float]) → osdatahub.filters.Filter

Constructs an OGC Filter for an attribute that is not equal to the input value

Parameters

property_name (str) – Property / attribute name to be filtered
value (Union[str, float]) – Value used in filter for comparison

Returns

A valid OGC XML filter

Return type

Filter

osdatahub.filters.overlaps(extent: osdatahub.extent.Extent) → osdatahub.filters.Filter

Constructs an OGC XML filter for data that overlaps the given extent

Parameters: extent (Extent) – The desired region to be filtered, given as an Extent object
Returns: A valid OGC XML filter
Return type: Filter

osdatahub.filters.single_attribute_filter(property_name, filter_name, value) → osdatahub.filters.Filter

osdatahub.filters.spatial_filter(operator: str, extent: osdatahub.extent.Extent) → osdatahub.filters.Filter

Constructs an OGC XML filter using the given operator string and the given extent

Parameters

operator (str) – Case-sensitive name of operator for OGC filter string
extent (Extent) – The desired region to be filtered, given as an Extent object

Returns

A valid OGC XML filter

Return type

Filter

osdatahub.filters.touches(extent: osdatahub.extent.Extent) → osdatahub.filters.Filter

Constructs an OGC XML filter for data that touches the given extent

Parameters: extent (Extent) – The desired region to be filtered, given as an Extent object
Returns: A valid OGC XML filter
Return type: Filter

osdatahub.filters.within(extent: osdatahub.extent.Extent) → osdatahub.filters.Filter

Constructs an OGC XML filter for data that is within the given extent

Parameters: extent (Extent) – The desired region to be filtered, given as an Extent object
Returns: A valid OGC XML filter
Return type: Filter

grow_list

class osdatahub.grow_list.GrowList(values: Optional[list] = None)

Bases: object

GrowList is a convenience class that behaves similarly to a normal list, except that it stores its length changes whenever it is extended with the extend() function.

extend(values: list)

Adds values onto the end of the GrowList

Parameters: values (list) – list of values to be added

property grown

Checks whether the GrowList has been expanded, or whether it has been extended with an empty list of values.

Returns: True suggests that the GrowList has recently grown, False suggests that it has been extended with an empty list
Return type: bool

ons_api

osdatahub.ons_api.get_ons_geom(ons_code: str) → dict

Gets coordinates of the boundary of the polygon for the ons_code

Parameters: ons_code (str) – ONS code
Returns: The json of the raw response
Return type: response_json (dict)

utils

osdatahub.utils.address_to_feature(address, crs)

The raw address from the PlacesAPI returns address in a JSON format where the coords have different keys depending on what CRS is requested. This function is needed to ensure that the keys of the coordinates are the same regardless of CRS.

Parameters

address (dict) – dictionary representation of an address
crs (str) – string representation of a coordinate system

Returns

dictionary representation of the input address

Return type

dict

Raises

ValueError – If CRS is not British National Grid, there should be
attributes called 'LAT' and 'LNG' in the address –

osdatahub.utils.addresses_to_geojson(address_list, crs)

Converts a list of GeoJSON gemetries to a FeatureCollection, where the list of GeoJSONs represent addresses

Parameters

address_list (list) – List of GeoJSON addresses
crs (str) – string representation of a coordinate system

Returns

cleaned FeatureCollection

Return type

FeatureCollection

osdatahub.utils.clean_features(feature_list: list, geom_type: str) → list

Post-processes API features to standardize geometry. In particular remove additional brackets and correct the nesting of brackets for multipolygons with holes.

Parameters

feature_list (list) – List of GeoJSON geometries
geom_type (str) – string describing which GeoJSON geometry type is
feature_list. (in) –

Returns

cleaned GeoJSON geometries

Return type

list

osdatahub.utils.clean_linestring(feature: dict) → dict

Post-process API LineString to standardize format by removing additional brackets.

Parameters: feature (dict) – GeoJSON LineString feature
Returns: GeoJSON LineString feature with extraneous brackets removed
Return type: dict

osdatahub.utils.clean_linestrings(feature_list: list) → list

Post-process API LineStrings to standardize format by removing additional brackets.

Parameters: feature_list (list) – List of GeoJSON LineStrings
Returns: List of GeoJSON LineStrings with extraneous brackets removed
Return type: list

osdatahub.utils.clean_polygon(feature: dict) → dict

Fixes the geometry of MultiPolygons, which are identified by being lists rather than dictionaries.

Parameters: feature (dict) – GeoJSON Polygon feature
Returns: Fixed GeoJSON Polygon feature
Return type: dict

osdatahub.utils.clean_polygons(feature_list: list) → list

Post-process API Polygons to fix geometries of MultiPolygons.

Parameters: feature_list (list) – List of GeoJSON Polygons
Returns: List of fixed GeoJSON Polygons
Return type: list

osdatahub.utils.features_to_geojson(feature_list, geom_type, crs) → geojson.feature.FeatureCollection

Converts a list of GeoJSON gemetries to a FeatureCollection

Parameters

feature_list (list) – List of GeoJSON geometries
geom_type (str) – string describing which GeoJSON geometry type is
feature_list. (in) –
crs (str) – string representation of a coordinate system

Returns

cleaned FeatureCollection

Return type

FeatureCollection

osdatahub.utils.is_new_api(response: Union[dict, osdatahub.grow_list.GrowList]) → bool

Checks whether the response came from the new API endpoint or the old API endpoint. The new endpoint response has 2 differences: it includes a “crs” item in the response geojson and each feature contains a new property called ‘GmlID’. This function checks for these differences and returns a boolean. :param response: response from the API. This could take any of 3 forms: the raw json response, :type response: Union[dict, GrowList] :param a single feature: :param or a GrowList containing features.:

Returns (bool): True if response came from new endpoint, False otherwise

osdatahub.utils.nest_polygons(coordinates)

Checks if polygons are oriented clockwise or anticlockwise, and uses the order to assessemble polygons with holes in correctly. Only needed to correct multipolygons with holes.

Parameters: coordinates (list) – Coordinates in a clockwise orientation are exteriors,

the following polygons of anticlockwise orientation are the holes for that polygons. Next clockwise coordinates are assumed to be exterior of new polygon.

Returns: A list of nested coordinates
Return type: new_polys (list)

osdatahub.utils.validate_in_range(value: float, minimum: float, maximum: float) → float

Checks that the input value is between the maximum and minimum values and returns the original value if it is.

Parameters

value (float) – value to check
minimum (float) – minimum value in range (inclusive)
maximum (float) – maximum value in range (inclusive)

Returns

returns input value if check passed

Return type

float

Raises

ValueError – Value should be between {minimum} and {maximum}, got {value}.