Pushing the boundaries with the Open Geography Portal API
The UK Office for National Statistics' Open Geography Portal provides a range of geospatial datasets under the Open Government Licence 3.0. Digital vector boundaries for different administrative and statistical geographies, postcode centroids and lookups are all available to freely download. This post will show you how to download digital vector boundaries for custom administrative geographies using the Open Geography Portal API.
What’s available?
Digital vector boundaries on the Open Geography Portal come as ESRI shapefiles, KML or GeoJSON files in full resolution or in one of three generalised formats:
- Generalised (20m)
- Super generalised (200m)
- Ultra generalised (500m)
It is recommended that high resolution formats are used for geospatial operations like point in polygon and generalised formats for interactive maps. Higher resolution boundaries are larger and will therefore take longer to load in a browser.
The boundaries are also available in two different coastal extents: ‘extent of the realm’ and ‘clipped to the coastline’. Unless you are mapping offshore islands it is recommended to use the ‘clipped to the coastline’ boundaries.
Maps using these boundaries must include the following attribution:
Contains National Statistics and OS data © Crown copyright and database right [YYYY]
An example
Task: Download the boundary for the local authority district of Trafford
1. Visit the Open Geography Portal and navigate to Boundaries > Administrative Boundaries > Local Authority Districts > 2018 Boundaries and choose Local Authority Districts (December 2018) Boundaries UK BGC from the list. This boundary layer has been generalised and clipped to the coastline.
2. Click the ‘API Explorer’ tab. This page allows you to construct an API query using the dropdown menus.
3. We intend to filter the UK Local Authority Districts boundaries by their attributes so we need to enter values into the ‘Query’ box. Click the + sign to reveal the attributes that we can filter by. We will select ‘lad18nm | Text’ because this contains the names of the local authority districts in the dataset. If you want to check what the other attributes refer to click the ‘Data’ tab for a preview.
4. Next we enter ‘Trafford’ into the free text box and click Enter on the keyboard.
5. The vector boundary layer has a number of attributes that we don’t need so just untick them. As you untick each box you’ll notice that the URL path displayed in the ‘Query URL’ box in the top right hand corner updates automatically.
6. Now click ‘Try It Out’ to see if the query returns a boundary from the API.
The results have been returned in JSON format. Unfortunately, there is no option in the dropdown menus to choose an alternative spatial format but we can retrieve one if we tweak the API query string.
7. You’ll notice that the URL path shown in the ‘Query URL’ box ends with ‘json’. We just need to change that to ‘geojson’. Copy the URL path and paste it into the address bar of a new browser window. Move the cursor to the end of the path and prefix ‘json’ with ‘geo’.
8. The where clause used to filter the boundary layer uses LIKE which will match records that contain TRAFFORD within ‘lad18nm’. Let’s substitute this for ‘=’. Hit Enter and your browser will return the boundary in GeoJSON format.
Now what can we do with this? There are several options:
- We could copy and paste the GeoJSON into an online tool like geojson.io. From here we can save the data in a variety of spatial formats and even add styling.
- If you are an R user we can load and visualise the boundary with:
library(sf)
sf <- st_read(“https://ons-inspire.esriuk.com/arcgis/rest/services/Administrative_Boundaries/Local_Authority_Districts_December_2018_Boundaries_UK_BGC/MapServer/0/query?where=lad18nm%20=%20%27Trafford%27&outFields=lad18cd,lad18nm,long,lat&outSR=4326&f=geojson")
plot(st_geometry(sf))- If you have access to a Geographical Information System like QGIS you can save the output shown in the browser with the extension .geojson and load it directly.
Going further
Since this is a query string we can change the parameters so that the API returns multiple local authority district boundaries. To do this it is helpful to first parse the URL path we used to retrieve the boundary of Trafford.
The API call
https://ons-inspire.esriuk.com/arcgis/rest/services/Administrative_Boundaries/Local_Authority_Districts_December_2018_Boundaries_UK_BGC/MapServer/0/query?where=lad18nm = ‘Trafford’&outFields=lad18cd,lad18nm,long,lat&outSR=4326&f=geojsonis made up of four different segments:
- The endpoint:
https://ons-inspire.esriuk.com/arcgis/rest/services/ - boundary layer:
Administrative_Boundaries/Local_Authority_Districts_December_2018_Boundaries_UK_BGC/ - resolution:
MapServer/0/ - and the query string:
query?where=lad18nm = ‘Trafford’&outFields=lad18cd,lad18nm,long,lat&outSR=4326&f=geojson
If we split the query string we will discover a further four segments:
+--------------+--------------------------+---------------------+
| Parameter | Value | Description |
+--------------+--------------------------+---------------------+
| ’where’: | lad18nm = ‘Trafford’ | equal to 'Trafford' |
| ’outFields’: | lad18cd,lad18nm,long,lat | return attributes |
| ’outSR’: | 4326 | in lon/lat coords |
| ’f’: | geojson | in GeoJSON format |
+--------------+--------------------------+---------------------+Let’s change the where parameter so that we return all of the 10 local authority districts in Greater Manchester. We will use the ‘IN’ operator which allows you to specify multiple values in a where clause:
lad18nm IN ('Bolton','Bury','Manchester','Oldham','Rochdale','Salford','Stockport','Tameside','Trafford','Wigan')When added to the full API call we have:
https://ons-inspire.esriuk.com/arcgis/rest/services/Administrative_Boundaries/Local_Authority_Districts_December_2018_Boundaries_UK_BGC/MapServer/0/query?where=lad18nm IN ('Bolton','Bury','Manchester','Oldham','Rochdale','Salford','Stockport','Tameside','Trafford','Wigan')&outFields=lad18cd,lad18nm,long,lat&outSR=4326&f=geojsonLet’s paste this into the address bar of a new browser window and copy the resulting GeoJSON into geojson.io:
If you need to encode the query as a URL string you can use online tools like the encoder on w3schools.com, urlencoder.io or the URLencode() function from the utils R package.
Final remarks
The Open Geography Portal’s API is an extremely useful service that allows users to download custom administrative and statistical geographies for the UK.
The API documentation contains a number of other parameters that aren’t available in the dropdown menus used to generate the URL query. We’d point users to geometryPrecision in particular because coordinates are typically returned in decimal degrees to 16 decimal places. We’d suggest that ‘geometryPrecision=6’ decimal places is fine for most purposes.
