To restrict your API query to a certain area, you’ll need to define
an “extent”. The extent object is represented in osdatahub
R package as an object of type qExtent which can convert
itself into the format needed by the API query. You can use an existing
polygon to create your extent by specifying the coordinates yourself, or
by using a polygon from another source, such as a shapefile.
There are several convenience functions to create common extent
types, which don’t require you to already have a polygon:
Extent from Polygon
If you have a polygon that defines the area you would like to query,
you can pass this to extent_from_polygon(). This function
will accept well-known text (WKT) strings, simple features objects from
the sf
package (types sf or sfc), or polygon
objects from the geos
package. This example shows how you can construct an extent to query
the NGD Features API for all the buildings within a rectangle.
library(osdatahub)
library(geos)
# Set an environment variable with you OS Data Hub API key.
# set_os_key('[YOUR KEY]')
# Define a rectangle by coordinates using `geos`.
xcoords <- c(435000, 437500, 437500, 435000, 435000)
ycoords <- c(114500, 114500, 116000, 116000, 114500)
rectangle <- geos::geos_make_polygon(x = xcoords, y = ycoords)
# Need to define the type of coordinates you are using.
# These are British National Grid, which using EPSG code 27700.
crs <- 'EPSG:27700'
# Create the extent
polygon_extent <- extent_from_polygon(rectangle,
crs = crs)
The extent is a type of list and it stores its polygon geometry as an
sf object in an item named polygon, so we can
plot it on a map to check it covers the area we wanted.
library(sf)
library(tmap)
library(maptiles)
# sf polygon of extent
polygon <- polygon_extent$polygon
# define the tile server parameters
osmaps <- list(src = 'OS Maps',
q = 'https://api.os.uk/maps/raster/v1/zxy/Light_3857/{z}/{x}/{y}.png?key={apikey}',
sub = '',
cit = 'Contains OS data © Crown copyright and database rights, 2025.')
# download tiles and compose basemap raster
poly_maps <- get_tiles(x = polygon,
provider = osmaps,
crop = FALSE,
cachedir = tempdir(),
apikey = get_os_key(),
verbose = FALSE)
# Plot the extent
plt <- tm_shape(poly_maps, bbox = polygon) +
tm_rgb() +
tm_shape(polygon) +
tm_borders(lty = 'dashed', lwd = 2) +
tm_grid(labels.format = list(big.mark = ""),
lines = FALSE) +
tm_credits(osmaps$cit)
plt
# The extent is then passed to the API to use in the query
results <- query_ngd(polygon_extent,
collection = 'bld-fts-buildingpart-1',
max_results = 100000,
returnType = 'sf',
key = get_os_key())
# When querying a large area or a dense data product,
# you may need to increase the max results limit to get all the data
# Plot the results on the existing map
plt <- plt +
tm_shape(results) +
tm_fill(col = 'darkblue')
plt
Extent from Bounding Box
If your extent is rectangular, instead of specifying all the
coordinates and constructing a polygon, you can use the
extent_from_bbox() function, which only requires the
coordinates of the South-West and North-East corners in the order (west,
south, east, north). This results in the same extent object as the
previous example, just in fewer lines of code.
You might use this if you want to return data that covers an area
currently visible in a web map, or if you want to match the bounds of
another data source, such as a raster, geodataframe or shapefile.
# Using the same coordinates as the previous example
west <- 435000
south <- 114500
east <- 437500
north <- 116000
bbox_extent <- extent_from_bbox(c(west, south, east, north),
crs = 'EPSG:27700')
# Check that both approaches give the same result
print(paste0('Extents are equal: ', bbox_extent$wkt == polygon_extent$wkt))
#> [1] "Extents are equal: TRUE"
Extent from Radius
extent_from_radius() is a convenient way to query for
data within a certain distance of a point location. This method can only
used with crs = 'EPSG:27700' and
crs = 'EPSG:3857', which are projected coordinate systems
and use units of meters. If you are using longitude and latitude, you
will need to convert to one of the two supported projections first.
This example shows how you can query for all road nodes within 200m
of a point location.
point <- c(441317, 112165)
distance <- 200
radial_extent <- extent_from_radius(centre = point,
radius = distance,
crs = 'EPSG:27700')
results <- query_ngd(radial_extent,
collection = 'trn-ntwk-roadnode-1',
crs = 'EPSG:27700',
max_results = 10000,
returnType = 'sf')
print(paste0('There are ', nrow(results), ' roadway nodes within ',
distance, 'm of (', point[1], ', ', point[2], ').'))
#> [1] "There are 105 roadway nodes within 200m of (441317, 112165)."
# download tiles and compose basemap raster
poly_maps <- get_tiles(x = radial_extent$polygon,
provider = osmaps,
crop = FALSE,
cachedir = tempdir(),
apikey = get_os_key(),
verbose = FALSE)
# Plot the query results
plt <- tm_shape(poly_maps, bbox = radial_extent$polygon) +
tm_rgb() +
tm_shape(radial_extent$polygon) +
tm_borders(lty = 'dashed', lwd = 2) +
tm_shape(results) +
tm_dots(col = 'darkblue', size = .5) +
tm_grid(labels.format = list(big.mark = ""),
lines = FALSE) +
tm_credits(osmaps$cit)
plt
Extent from National Grid Code
The National Grid provides a unique spatial reference system for
Great Britain across multiple spatial scales. A series of grid squares
measuring 100km covers Great Britain. These squares are further divided
into smaller squares. The smaller squares are identified by numbers of
‘eastings’ and ‘northings’. Combining the letters and numbers generates
a British National Grid (BNG) code that can identify a grid square
location. More information on BNG codes is available here.
The BNG square can be represented as a polygon geometry where the
length of the side equal to the scale of the grid reference.
# Identify a BNG square
bngcode <- 'SU3715'
bng_extent <- extent_from_bng(bngcode)
# The CRS will always be EPSG:27700 for BNG extents.
print(bng_extent)
#> OS Data Hub Query Extent
#> Created from: BNG
#> Bounding box: 437000 115000 438000 116000
#> Coord. Ref. Sys.: epsg:27700
# Query the API
results <- query_ngd(bng_extent,
collection = 'bld-fts-buildingpart-1',
crs = 'EPSG:27700',
max_results = 10000,
returnType = 'sf')
# download tiles and compose basemap raster
poly_maps <- get_tiles(x = bng_extent$polygon,
provider = osmaps,
crop = FALSE,
cachedir = tempdir(),
apikey = get_os_key(),
verbose = FALSE)
# Plot the results
plt <- tm_shape(poly_maps, bbox = bng_extent$polygon) +
tm_rgb() +
tm_shape(bng_extent$polygon) +
tm_borders(lty = 'dashed', lwd = 2) +
tm_shape(results) +
tm_fill(col = 'darkblue') +
tm_grid(labels.format = list(big.mark = ""),
lines = FALSE) +
tm_credits(osmaps$cit)
plt
