Package 'boundr'

Title: Retrieve Area Boundaries and Data from the ONS Open Geography Portal
Description: The main purpose of this package is to download area lookups and boundaries (in GeoJSON format) using the ONS Open Geography API, for all areas at a specified level within a specified area.
Authors: Francis Barton [aut, cre]
Maintainer: Francis Barton <[email protected]>
License: MIT + file LICENSE
Version: 0.3.99
Built: 2024-10-04 10:33:45 UTC
Source: https://codeberg.org/francisbarton/boundr

Help Index

Use an existing tibble as the basis for a spatial query

Description

If you have a tibble such as those produced by lookup() - that is, there is a column of geographical ONS codes ending in 'cd' - simply use this table as the basis for retrieving the relevant boundaries or centroids. add_geometry_to_table() will use the lefthand-most column ending with "cd".

Usage

add_geometry_to_table(
  tbl,
  opts = boundr_options(),
  geometry = c("boundaries", "centroids")
)

add_geometry(
  tbl,
  opts = boundr_options(),
  geometry = c("boundaries", "centroids")
)

Arguments

tbl

A tibble with a column containing ONS geographical codes.
opts

Should be set with the boundr_options() function. See ?boundr_options for detail on what can be set by the user, and on the default values.
geometry

character. Two options: "boundaries" (the default) and "centroids". By default, bounds() will return area boundaries. Set this explicitly to "centroids" to get area centroids instead.

Value

If successful, will return the initial table with an additional geometry column added. Duplicate rows will be removed.

Examples

tibble::tibble(wd23cd = c("S13003001", "N08000520", "W05001522")) |>
  add_geometry_to_table()

Use this to set custom options for bounds()

Description

opts() is an alias for this function.

Usage

boundr_options(
  resolution = res_codes(),
  return_width = c("tidy", "full", "minimal"),
  crs = 4326,
  query_option = NULL
)

opts(
  resolution = res_codes(),
  return_width = c("tidy", "full", "minimal"),
  crs = 4326,
  query_option = NULL
)

Arguments

resolution

character. See res_codes() for the potential options. How generalised should the boundary be, and whether coastal boundaries should adhere to the coastline or to the full territorial extent. BGC by default (G = Generalised (20m), C = limited to the coastline.) F indicates Full resolution; S indicates Super-generalised (200m); U indicates Ultra- generalised (500m) boundary resolution. Use E instead of C for full extent boundaries (e.g. BFE). Not all combinations are available. Ignored if geometry is set to "centroids".
return_width

character. How many of the possible columns in the returned table to keep. Options are "tidy", "full" or "minimal". "Tidy" aims to return four data columns (usually) - two columns for the lookup level codes and names, and two for the within level codes and names. Plus a geometry column. "Full" aims to return all data columns from the lookup. "Minimal" aims to return just the two (usually!) data columns relating to lookup_level. If within is not supplied then "tidy" will be equivalent to "minimal".
crs

The Coordinate Reference System (CRS) code to use
query_option

numeric. Defaults to 1, which means that the URL will just be the first one from the list of possible services resulting from the level and year filters above. If this does not give you what you want, you can run the function again with a different option from the list.

Examples

boundr_options(crs = 27700) # Set the CRS to British National Grid
boundr_options(return_width = "full") # Ask boundr to return all data columns

Return boundary data at a specified level and area from the ONS OG API

Description

Return boundary data at a specified level and area from the ONS OG API

Usage

bounds(
  lookup_level,
  within_level = NULL,
  within_names = NULL,
  within_codes = NULL,
  lookup_year = NULL,
  within_year = NULL,
  opts = boundr_options(),
  geometry = c("boundaries", "centroids")
)

Arguments

lookup_level

character. Lower level area code eg "lsoa", "wd", "lad".
within_level

character. Higher level area code eg "lad", "cty", "icb". (That is, higher (conceptually) than lookup_level; aka larger than lookup!). If not supplied, this uses the default NULL, and just data for lookup_level will be returned. In this case, within_names and within_codes (if supplied) will instead be taken to refer to, and used to filter at, the lookup_level level.
within_names, within_codes

character. In order to restrict data returned to a specific area, either within_names or within_codes must be provided. Otherwise all available boundaries at that level will be retrieved. Use place names eg "Essex" to restrict to a certain geographical area. Or use ONS area codes eg "W02000103" likewise (this is useful with wards, where there are many that share identical names). To use this argument to filter within_level, the within_level must be specified! Otherwise {boundr} will apply them to lookup_level instead. See examples. Vectors of multiple names or multiple codes can be supplied. If you supply both within_names and within_codes, only within_names will be used; (within_codes will be ignored).
lookup_year

numeric or character. A specific year for data relating to lookup_level, if you need it. Defaults to NULL, which then aims to return data for the most recent year available. Provide as YYYY.
within_year

numeric or character. A specific year for data relating to within_level, if you need it. Defaults to NULL, which then aims to return data for the most recent year available. Provide as YYYY.
opts

Should be set with the boundr_options() function. See ?boundr_options for detail on what can be set by the user, and on the default values.
geometry

character. Two options: "boundaries" (the default) and "centroids". By default, bounds() will return area boundaries. Set this explicitly to "centroids" to get area centroids instead.

Value

an sfc tibble (data frame with geometry)

See Also

boundr_options

Examples

bounds("msoa", "lad", "Swansea")
bounds("wd", "lad", "Shepway", within_year = 2016) # Shepway no longer exists
bounds("rgn", opts = boundr_options(resolution = "BUC"))
bounds("par", "lad", "Isles of Scilly") # par = "parish"
bounds("spr")
bounds("npark", within_names = "Bannau Brycheiniog")
bounds("msoa", "utla", "Swindon", geometry = "centroids")

Create a lookup table by querying the ONS OpenGeography API

Description

Create a lookup table by querying the ONS OpenGeography API

Usage

lookup(
  lookup_level,
  within_level = NULL,
  within_names = NULL,
  within_codes = NULL,
  lookup_year = NULL,
  within_year = NULL,
  opts = boundr_options()
)

Arguments

lookup_level

character. Lower level area code eg "lsoa", "wd", "lad".
within_level

character. Higher level area code eg "lad", "cty", "icb". (That is, higher (conceptually) than lookup_level; aka larger than lookup!). If not supplied, this uses the default NULL, and just data for lookup_level will be returned. In this case, within_names and within_codes (if supplied) will instead be taken to refer to, and used to filter at, the lookup_level level.
within_names, within_codes

character. In order to restrict data returned to a specific area, either within_names or within_codes must be provided. Otherwise all available boundaries at that level will be retrieved. Use place names eg "Essex" to restrict to a certain geographical area. Or use ONS area codes eg "W02000103" likewise (this is useful with wards, where there are many that share identical names). To use this argument to filter within_level, the within_level must be specified! Otherwise {boundr} will apply them to lookup_level instead. See examples. Vectors of multiple names or multiple codes can be supplied. If you supply both within_names and within_codes, only within_names will be used; (within_codes will be ignored).
lookup_year

numeric or character. A specific year for data relating to lookup_level, if you need it. Defaults to NULL, which then aims to return data for the most recent year available. Provide as YYYY.
within_year

numeric or character. A specific year for data relating to within_level, if you need it. Defaults to NULL, which then aims to return data for the most recent year available. Provide as YYYY.
opts

Should be set with the boundr_options() function. See ?boundr_options for detail on what can be set by the user, and on the default values.

Value

A tibble

Examples

lookup("msoa", "lad", "Swindon")
lookup("wd", "sener", opts = opts(return_width = "full"))

A list of all available resolutions for boundary geometries in the current OpenGeography schema. Not all resolutions are available for all area types! The most common ones are listed first, with the "generalised" (20m resolution) BGC being the preferred option if you don't specify one.

Description

A list of all available resolutions for boundary geometries in the current OpenGeography schema. Not all resolutions are available for all area types! The most common ones are listed first, with the "generalised" (20m resolution) BGC being the preferred option if you don't specify one.

Usage

res_codes()