query_nearest_places: Query the OS Places API

In osdatahub: Easier Interaction with the Ordnance Survey Data Hub

Query the OS Places API

Description

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

Usage

query_nearest_places(
  point,
  point_crs,
  radius = 100,
  output_crs = "EPSG:27700",
  classification_code,
  logical_status_code,
  dataset = "DPA",
  key = get_os_key(),
  returnType = c("geojson", "list", "sf"),
  ...
)

Arguments

point	A set of coordinates as a numeric vector, an object of class geos, or an object of class sf.
point_crs	(character or numeric) The identifier for coordinate reference system information for the point feature.
radius	(numeric) The search radius in metres (max. 1000). Default is 100.
output_crs	(character or numeric) The output CRS. Defaults to “EPSG:27700”. Other options are EPSG:4326 or EPSG:3857.
classification_code	Classification codes to filter query by.
logical_status_code	Logical status code to filter query by.
dataset	(character) The dataset to return. Multiple values can be provided as a vector. Default is 'DPA'.
key	(character) OS API key. Default action is to search for an environment variable using get_os_key().
returnType	(character) Return the query results as the raw 'geojson', a nested 'list' object containing the returns, or convert them into Simple Features and return an object of class 'sf'.
...	Additional parameters (not currently used).

Details

The OS Places API provides a detailed view of an address and its life cycle. Use this function to query Places to find the address nearest to a given point location.

The Places API contains all the records of AddressBase® Premium and AddressBase® Premium – Islands and so provides all the information relating to an address or property from creation to retirement. It contains local authority, Ordnance Survey and Royal Mail® addresses, current addresses, and alternatives for current addresses, provisional addresses (such as planning developments) and historic information, plus OWPAs and cross references to the OS MasterMap® TOIDS®. OS Places API contains addresses located within the United Kingdom, Jersey, Guernsey and the Isle of Man. For address records in Jersey and Guernsey the coordinates will be ‘0.0’ as they fall outside of the British National Grid. This means they are not compatible with the GeoSearch operations.

Technical details on the Places API are documented on the Data Hub: https://osdatahub.os.uk/docs/places/technicalSpecification.

Note: the Places API requires a Premium API key.

Value

A GeoJSON string with the results of the API query, a list object, or an object of class sf based on the returnType parameter.

See Also

query_places(), query_postcode_places(), query_uprn_places()

Examples

# Find address nearest to a point
pt <- c(437292.4, 115541.9)

results <- query_nearest_places(pt, point_crs = 'EPSG:27700')

osdatahub documentation built on April 11, 2025, 5:52 p.m.