query_names: Query the OS Names API

In osdatahub: Easier Interaction with the Ordnance Survey Data Hub

Query the OS Names API

Description

Retrieve information from a geographic directory of identifiable places based on a free text search.

Usage

query_names(
  x,
  limit = 100,
  bounds,
  bbox_filter,
  local_type,
  key = get_os_key(),
  returnType = c("geojson", "list", "sf"),
  ...
)

Arguments

x	The free text search parameter.
limit	(numeric) The maximum number of features to return. Default is 100.
bounds	Biases the search results to a certain area. Should be of type qExtent created by the extent_from_* functions with CRS = EPSG:27700.
bbox_filter	Filters the results to a certain area. Should be of type qExtent created by the extent_from_* functions with CRS = EPSG:27700.
local_type	(character) Filters the results to certain local types. The available local types can be found at: https://osdatahub.os.uk/docs/names/technicalSpecification.
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 Names API is a geographic directory containing basic information about identifiable places. Those places are divided into themes, but the name of the place is the key property used in queries. The free text search is intended to be a "fuzzy" search.

Within OS Names, place names aren’t unique. Extra location details are provided to help users refine their queries and accurately identify the named place they’re interested in. These details include postcode district, populated place, district/borough, county/unitary authority, European region and country. Queries can also be refined by supplying bounding boxes or local types to search.

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

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_nearest_names(), extent

Examples

# Find names places by text search.
results <- query_names('Buckingham Palace', limit = 5)

# Use filters
results <- query_names('Southampton', local_type = 'City')

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

results <- query_names('Norwich', bbox_filter = extent)

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