geo_get: Get boundaries for smaller areas within a larger area

View source: R/geo_get.R

geo_getR Documentation

Get boundaries for smaller areas within a larger area


The ONS OpenGeography Portal ( is a great resource for area boundary and data lookups within the UK. This program focuses on areas within England and Wales only, initially.


  within_level = NULL,
  bounds_cd = FALSE,
  within_cd = FALSE,
  include_msoa = NULL,
  return_style = "tidy",
  include_welsh_names = NULL,
  return_boundaries = TRUE,
  return_centroids = FALSE,
  centroid_fields = FALSE,
  shape_fields = FALSE,
  spatial_ref = 4326,
  quiet_read = TRUE



The lowest level at which to return codes and names, eg "LSOA". Has to be one of "lsoa", "msoa", "wd/ward", "lad", "cty/county". Case-insensitive.


The name of a geographic area to filter by eg "Swindon", "Gloucestershire", "Wales", or a set of area codes (with bounds_cd or within_cd).


Upper geographic level to filter at. eg if filtering to find all LSOAs in a local authority, within_level will be "lad". Has to be one of "wd/ward", "lad/ltla", "cty/county", "utla/upper", "rgn/region", "cauth" or "ctry/country". Case-insensitive. Not all combinations of bounds_level and within_level make sense or are possible! NB "county" includes metropolitan counties such as "Tyne and Wear" and "West Midlands".


When you just supply a list of area codes for places you want boundaries for. NB this relates to lower areas, "bounds" level.


Usually you'll build the query with a place name to search within. But sometimes you may wish to pass in a vector of area codes instead (if that's all you have, or more likely if you are querying within wards, which don't have unique names (there's a lot of Abbey wards in England!)). If you're passing in area codes not names, set this to TRUE. NB this only applies to the higher, "within", level.


If bounds_level = LSOA and return_style = "tidy", whether to also include MSOA columns (in "tidy" return style). If bounds_level is MSOA, this will be forced to TRUE.


"tidy" (the default) means all available columns between bounds_level and within_level will be returned, but with any empty columns removed. "simple" means that only the code and name (cd and nm) columns for bounds_level and within_level are returned - other columns are omitted. "minimal" means 'only return the columns for bounds_level'.


Only makes a difference when bounds_level = msoa, or when bounds_level = lsoa and return_style = "tidy". FALSE returns no Welsh language columns. TRUE attempts to return Welsh language LAD and MSOA names where relevant. NULL (the default) means that an educated decision will be made by the program, based on whether any of the areas returned have "W" codes.


whether to retrieve object boundaries data from the API. Default TRUE. If return_boundaries and return_centroids and centroid_fields are all FALSE, a plain summary df without any geometry will be returned.


whether to retrieve area centroids instead of boundaries. Default FALSE. If set to TRUE then it will override return_boundaries whether that was set TRUE or otherwise. If return_boundaries and return_centroids are both FALSE, a plain summary data frame without geometry will be returned.


Boolean, default FALSE. Whether to include BNG eastings, northings, lat and long fields in the return. NB this doesn't apply to direct (population-weighted) centroid queries.


Boolean, default FALSE. Whether to include Shape__Area and Shape__Length fields in the return when returning boundaries.


The (EPSG) spatial reference of any returned geometry. Default value: 4326 ("WGS 84"). This parameter is ignored peacefully if no geometry is returned/returnable, eg lookup queries


Controls quiet parameter to sf::st_read


I want a better name for this function! Suggestions welcome...


a data frame or an sf (simple features) object (data frame with geometries)


geo_get("wd", "Swindon", "lad")
geo_get("msoa", "Swansea", "lad", return_centroids = TRUE) %>%
geo_get("lsoa", "Zetland", "ward", shape_fields = TRUE)
geo_get(bounds_level = "lad",
  within = "Gloucestershire",
  within_level = "cty",
  return_style = "simple",
  return_boundaries = FALSE)

francisbarton/jogger documentation built on Aug. 6, 2022, 2:34 a.m.