query_places: Query the OS Places API

In osdatahub: Easier Interaction with the Ordnance Survey Data Hub

Query the OS Places API

Description

Retrieve information on UK addresses within a geographic area or based on a free text search.

Usage

query_places(x, ...)

## S3 method for class 'qExtent'
query_places(
  x,
  output_crs,
  limit = 100,
  classification_code,
  logical_status_code,
  dataset = "DPA",
  key = get_os_key(),
  returnType = c("geojson", "list", "sf"),
  ...
)

## S3 method for class 'character'
query_places(
  x,
  output_crs = "EPSG:27700",
  limit = 100,
  classification_code,
  logical_status_code,
  minmatch,
  matchprecision,
  dataset = "DPA",
  key = get_os_key(),
  returnType = c("geojson", "list", "sf"),
  ...
)

Arguments

x	Either a polygon created with extent_from_* functions defining the geographic area, or a character string to search.
...	Additional parameters (not currently used).
output_crs	Output CRS. Optional or will be defined by the extent.
limit	(numeric) The maximum number of features to return. Default is 100 which is the max return per page from the Data Hub.
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'.
minmatch	The minimum matching score a result has to be returned.
matchprecision	The decimal point position at which the match score value is to be truncated.

Details

The OS Places API provides a detailed view of an address and its life cycle. Use this function to query Places based on a geographic area or a free text search.

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

extent, query_nearest_places(), query_postcode_places(), query_uprn_places()

Examples

# Addresses within a bounding box
extent <- extent_from_bbox(c(600000, 310200, 600900, 310900),
                           crs = 'EPSG:27700')

results <- query_places(extent, limit = 50)

# Find addresses by text search.
results <- query_places('Ordnance Survey, Adanac Drive, SO16',
                        minmatch = 0.5)

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