OS Data Hub Places API

PlacesAPI

class osdatahub.PlacesAPI.places_api.PlacesAPI(key: str)

Bases: object

Main class for querying the OS Places API (https://osdatahub.os.uk/docs/places/overview)

Parameters

key (str) – A valid OS API Key. Get a free key here - https://osdatahub.os.uk/

Example:

from osdatahub import PlacesAPI, Extent
from os import environ

key = environ.get("OS_API_KEY")
places = PlacesAPI(key)
extent = Extent.from_radius((437293, 115515), 800, "EPSG:27700")
results = places.query(extent, limit=100)
HEADERS = {'headers': "{'Content-Type': 'application/json'}", 'method': 'POST'}
find(text: str, output_crs: str = 'EPSG:27700', limit: int = 100, classification_code: Optional[Union[collections.abc.Iterable, str]] = None, logical_status_code: Optional[Union[str, int]] = None, minmatch: Optional[float] = None, matchprecision: Optional[int] = None, dataset: Optional[Union[str, collections.abc.Iterable]] = None) → geojson.feature.FeatureCollection

A free text query of the OS Places API

Parameters

  • text (str) – The free text search parameter

  • output_crs (str, optional) – The intended output CRS

  • limit (int, optional) – The maximum number of features to return. Defaults to 100.

  • classification_code (str|Iterable[str], optional) – Classification codes to filter query by

  • logical_status_code (str|int, optional) – logical status codes to filter query by

  • minmatch (float, optional) – The minimum match score a result has to have to be returned

  • matchprecision (int, optional) – The decimal point position at which the match score value is to be truncated

  • dataset (str|Iterable, optional) – The dataset to return. Multiple values can be sent, separated by a comma. Default: DPA.

Returns

The results of the query in GeoJSON format

Return type

FeatureCollection

nearest(point: tuple, point_crs: str, radius: float = 100, output_crs: str = 'EPSG:27700', classification_code: Optional[Union[collections.abc.Iterable, str]] = None, logical_status_code: Optional[Union[str, int]] = None, dataset: Optional[Union[str, collections.abc.Iterable]] = None) → geojson.feature.FeatureCollection

Takes a pair of coordinates (X, Y)/(Lon, Lat) as an input to determine the closest address.

Parameters

  • point (tuple) – A set of coordinates

  • point_crs (str) – The crs corresponding to the point coordinates

  • radius (float) – The search radius in metres (max. 1000). Defaults to 100.

  • output_crs (str, optional) – The intended output CRS. Defaults to “EPSG:27700”.

  • classification_code (str|Iterable[str], optional) – Classification codes to filter query by

  • logical_status_code (str|int, optional) – logical status codes to filter query by

  • dataset (str|Iterable, optional) – The dataset to return. Multiple values can be sent, separated by a comma. Default: DPA.

Returns

The results of the query in GeoJSON format

Return type

FeatureCollection

postcode(postcode: str, output_crs: str = 'EPSG:27700', limit: int = 100, classification_code: Optional[Union[collections.abc.Iterable, str]] = None, logical_status_code: Optional[Union[str, int]] = None, dataset: Optional[Union[str, collections.abc.Iterable]] = None) → geojson.feature.FeatureCollection

A query based on a property’s postcode. The minimum for the resource is the area and district

e.g. SO16, and will accept a full postcode consisting of the area, district, sector and unit e.g. SO16 0AS

Parameters

  • postcode (str) – The postcode search parameter

  • output_crs (str, optional) – The intended output CRS. Defaults to “EPSG:27700”.

  • limit (int, optional) – The maximum number of features to return. Defaults to 100.

  • classification_code (str|Iterable[str], optional) – Classification codes to filter query by

  • logical_status_code (str|int, optional) – logical status codes to filter query by

  • dataset (str|Iterable, optional) – The dataset to return. Multiple values can be sent, separated by a comma. Default: DPA.

Returns

The results of the query in GeoJSON format

Return type

FeatureCollection

query(extent: osdatahub.extent.Extent, output_crs: Optional[str] = None, limit: int = 100, classification_code: Optional[Union[str, collections.abc.Iterable]] = None, logical_status_code: Optional[Union[str, int]] = None, dataset: Optional[Union[str, collections.abc.Iterable]] = None) → geojson.feature.FeatureCollection

Run a query of the OS Places API within a given extent

Parameters

  • extent (Extent) – The geographical extent of your query

  • output_crs (str, optional) – The intended output CRS

  • limit (int, optional) – The maximum number of features to return. Defaults to 100.

  • classification_code (str|Iterable[str], optional) – Classification codes to filter query by

  • logical_status_code (str|int, optional) – logical status codes to filter query by

  • dataset (str|Iterable, optional) – The dataset to return. Multiple values can be sent, separated by a comma. Default: DPA.

Returns

The results of the query in GeoJSON format

Return type

FeatureCollection

uprn(uprn: int, output_crs: str = 'EPSG:27700', classification_code: Optional[Union[collections.abc.Iterable, str]] = None, logical_status_code: Optional[Union[str, int]] = None, dataset: Optional[Union[str, collections.abc.Iterable]] = None) → geojson.feature.FeatureCollection

A query that takes a UPRN as the search parameter

Parameters

  • uprn (int) – A Valid UPRN

  • output_crs (str, optional) – The intended output CRS. Defaults to “EPSG:27700”.

  • classification_code (str|Iterable[str], optional) – Classification codes to filter query by

  • logical_status_code (str|int, optional) – logical status codes to filter query by

  • dataset (str|Iterable, optional) – The dataset to return. Multiple values can be sent, separated by a comma. Default: DPA.

Returns

The results of the query in GeoJSON format

Return type

FeatureCollection