OS Data Hub Names API

NamesAPI

class osdatahub.NamesAPI.names_api.NamesAPI(key: str)

Bases: object

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

Parameters

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

Example:

from osdatahub import NamesAPI
from os import environ

key = environ.get("OS_API_KEY")
names = NamesAPI(key)
results = names.find("Buckingham Palace", limit=5)
HEADERS = {'headers': "{'Content-Type': 'application/json'}", 'method': 'POST'}
find(text: str, limit: int = 100, bounds: Optional[osdatahub.extent.Extent] = None, bbox_filter: Optional[osdatahub.extent.Extent] = None, local_type: Optional[Union[collections.abc.Iterable, str]] = None) → geojson.feature.FeatureCollection

A free text query of the OS Names API

Parameters

  • text (str) – The free text search parameter

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

  • bounds (Extent, optional) – Biases the results to a certain area. Must be British National Grid (EPSG:27700) CRS

  • bbox_filter (Extent, optional) – Filters the results to a certain area. Must be British National Grid (EPSG:27700) CRS

  • local_type (Union[Iterable, str], optional) – Filters the results to certain local types. Available local types can be found at the bottom of https://osdatahub.os.uk/docs/names/technicalSpecification

Returns

The results of the query in GeoJSON format

Return type

FeatureCollection

nearest(point: tuple, radius: float = 100, local_type: Optional[Union[collections.abc.Iterable, str]] = None) → geojson.feature.FeatureCollection

Takes a pair of coordinates (X, Y) as an input to determine the closest name.

Parameters

  • point (tuple) – A set of coordinates in British National Grid (EPSG:27700) format

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

  • local_type (Union[Iterable, str], optional) – Filters the results to certain local types. Available local types can be found at the bottom of https://osdatahub.os.uk/docs/names/technicalSpecification

Returns

The results of the query in GeoJSON format

Return type

FeatureCollection