-
Notifications
You must be signed in to change notification settings - Fork 2
Requesting geographic information
Parent endpoint: /api/v1/geo
Note: Child endpoints marked ✅ should work in the prototype. For ☑️ some params are not yet available.
/api/v1/geo/list?{parameters} ✅
List names, codes and selected metadata for all available geographies. Parameters can be added to filter the list or add additional metadata fields.
| Parameter | Description |
|---|---|
| geo | Provide a group (eg. "ltla") or a GSS code (eg. "K02000001") to filter the list (default "all") |
| year | Filter geographies by year or "all" for no time filter (default "latest") |
| indicator | Filter to only include geographies available for a specific indicator (default "all") |
| asLookup | Returns a lookup keyed by GSS code instead of an array/list (default "false") |
| groupByLevel | Groups results by geography level (default "false", ignored if asLookup=true) |
| includeParents | Include the GSS code for the parents of each area (default "false") |
| includeChildren | Include the GSS code for the children of each area (default "false") |
| includeDates | Include start and end dates for new/old areas (default "false") |
| includeLevel | Includes the geography level code (eg. "rgn") in the response (default "false") |
/api/v1/geo/levels?{parameters} ☑️
Lists the geography levels contained within the app (eg. "ltla") and their type prefixes (eg. "E06"). Optionally includes all the individual area codes within each level.
| Parameter | Description |
|---|---|
| year | Filter area code lists (see below) by validity year (default "latest") |
| includeAreas | Include area codes for all the individual areas at each level (default "true") |
/api/v1/geo/lookup/{code} ✅
Returns a GeoJSON feature containing a boundary polgon and extended metadata for a specific area idenfied by its GSS code. Metadata includes names, codes, geography level, and parent and child areas. The geographic bounding box and centroid are also included.
/api/v1/geo/related/{code} ✅
Returns areas related to a specific area identified by its GSS code. Related areas include "parents", "childen", "siblings" and "similar" areas. These relations can also be requested individually using the requests below.
/api/v1/geo/related/{code}/parents ✅
List codes of all parents for a specific geography.
/api/v1/geo/related/{code}/children?{parameters} ✅
List codes of all immediate children of a specific geography. By default, this will give the immediate children, but it is also possible to request children at a lower level/grouping using the geoLevel parameter (eg. /api/v1/geo/related/E12000001/children?geoLevel=ltla).
/api/v1/geo/related/{code}/siblings?{parameters} ✅
List codes of all siblings of a specific geography that share the same parent. By default, the siblings will be within the immediate parent, but a parentLevel parameter can also be defined to find siblings within a wider geographic area (eg. /api/v1/geo/related/E06000001/siblings?parentLevel=rgn).
/api/v1/geo/related/{code}/similar ✅
Lists all statistically similar areas for a specific area (defined by GSS code). These include:
- Areas in the same cluster by demography, economy and all indicators.
- 20 most similar areas by demography, economy and all indicators.
/api/v1/geo/boundaries.{format}?{parameters} ✅
Return generalised (low resolution) geographic boundaries in "geojson" or "topojson" format. Boundaries can be filtered using the following parameters:
| Parameter | Description |
|---|---|
| year | Geography validity year (default "latest") |
| country | Any combination of "E", "N", "S" or "W" (default "all") |
| geoLevel | Geography group (eg. "rgn") or "all" (default "ltla") |
/api/v1/geo/search/{string}?{parameters} ✅
Takes a search string (eg. "norwich") and returns a list of areas that contain that string within their name. Parameters can also be used to refine the search result.
| Parameter | Description |
|---|---|
| year | Filter geographies by year or "all" for no time filter (default "latest") |
| limit | The maximum number of results to return (default "10") |
| offset | Start index for results. Use with limit to paginate results (default "0") |
| geoLevel | Geography groups (eg. "rgn,ltla") or "all" (default "all") |
| searchPostcodes | If the search string looks like a postcode, then postcode results are returned (default "false") |
| groupByLevel | Groups results by geography level (default "false") |
| includeDates | Include start and end dates for new/old areas (default "false") |
/api/v1/geo/reverse?lng={longitude}&lat={latitude}&{parameters} ✅
Returns a list of areas that a specific geographic point (longitude/latitude) falls within, along with their metadata. The returned geographies can be filtered/modified using the following parameters:
| Parameter | Description |
|---|---|
| year | Filter geographies by year or "all" for no time filter (default "latest") |
| geoLevel | Geography group (eg. "rgn") or "all" (default "all") |
| groupByLevel | Groups results by geography level (default "false") |
| includeDates | Include start and end dates for new/old areas (default "false") |
/api/v1/geo/postcodes/{code}?{parameters} ✅
Returns metadata (longitude/latitude) for a postcode and a list of geographies that it falls within. Requires a complete postcode (eg. "PO14 5RR"), but is not sensitive to case or whitespace (eg. "po145rr" would return the same results as the previous example). The returned geographies can be filtered/modified using the following parameters:
| Parameter | Description |
|---|---|
| year | Filter geographies by year or "all" for no time filter (default "latest") |
| geoLevel | Geography group (eg. "rgn") or "all" (default "all") |
| groupByLevel | Groups results by geography level (default "false") |
| includeDates | Include start and end dates for new/old areas (default "false") |
/api/v1/geo/postcodes/{partial_code}/autocomplete ✅
Returns a list of postcodes with metadata (longitude/latitude) matching the search criteria. Any incomplete postcode is valid ("P", "PO", "PO14" etc) and case is not sensitive.
| Parameter | Description |
|---|---|
| limit | The maximum number of results to return (default "10") |
| offset | Start index for results. Use with limit to paginate results (default "0") |