-
Notifications
You must be signed in to change notification settings - Fork 2
Requesting data
Parent endpoint: /api/v1/data
Note: Example requests marked ✅ should work in the prototype. For ☑️ some params are not yet available.
The general structure for data requests is as follows:
/api/v1/data.{format}?{parameters}
The {format} portion of the URL can have the following values:
| Value | Data format |
|---|---|
| csv | CSV (comma-separated values) ✅ |
| csvw | CSVW-compliant JSON metadata to accompany CSV ✅ |
| json | JSON-Stat ✅ |
| ods | AF-compliant ODS spreadsheet (Excel-compatible) |
| rows.json | JSON row-oriented array |
| cols.json | JSON column-oriented arrays ✅ |
The above formats are all described here, along with examples.
The {parameters} ☑️ portion of the URL can include anything in the table below. The following sub-sections below describe the ways to use each parameter.
(Note: If any parameters are not explicitly included they are assumed to have the default parameters).
| Parameter | Description |
|---|---|
| topic | Select one or more topics (default "all") |
| indicator | Select one or more individual indicators (default "all") |
| excludeMultivariate | Option to exclude multivariate indicators (default "false") |
| time | Select a date or range of dates (default "latest") |
| timeNearest | Define whether to return any values if the date is out of range (default "none") |
| geo | Select one or more area or group of areas (default "all") |
| geoExtent | Define a geographic extent by GSS code (default is UK "K02000001") |
| geoCluster | Only return areas within a specific cluster (default is "all") |
| hasGeo | Filter for indicators that include a specific GSS code (default is "all") |
| dimension_{code} | Filter on specific non-time and non-geo dimensions in a dataset (default "all") |
| measure | Filter which measures to include in a response (default "all") |
| includeNames | Choose whether to include area names in responses (default "false") |
| includeStatus | Choose whether to include observation status in responses (default "false") |
Select one or more comma-separated topic or sub-topic codes from the taxonomy (see "list topics"), or use "all" (default) to return all available indicators.
Example: /api/v1/data.csv?topic=housing,crime ✅
Select one or more comma-separated indicator codes (see "list indicators"), or use "all" (default) to return all available indicators.
Example: /api/v1/data.csv?indicator=employment-rate ✅
Note: When used together the topic and indicator filters are "additive". Selecting topic=housing&indicator=employment-rate will select all housing indicators plus "employment rate", which is categorised as an economic indicator.
Set to "true" to exclude multi-variate indicators from the response. Default is "false".
Example: /api/v1/data.csv?excludeMultivariate=true ✅
Note: This parameter will not exclude indicators that have been selected explicitly using the indicator parameter.
Select a date or range of dates (comma-separated start and end dates). Dates can be in the format YYYY, YYYY-MM or YYYY-MM-DD. A value of "latest", "earliest" or "all" is also accepted. The filtering behaviour is described below.
For individual dates:
| Format | Behaviour |
|---|---|
| latest | Return only the value for the most recent date (default) |
| earliest | Return only the value for the earliest date |
| all | Return values for all dates |
| YYYY | Return the last available value in the given year |
| YYYY-MM | Return the last available value in the given month |
| YYYY-MM-DD | Only return a value if it falls on the precise date specified |
For date ranges:
| Format | Behaviour |
|---|---|
| YYYY,YYYY | Return values from the start of the first year to the end of the second year |
| YYYY-MM,YYYY-MM | Return values from the start of the first month to the end of the last month |
| YYYY-MM-DD,YYYY-MM-DD | Return values for all dates in the range, inclusive |
Example: /api/v1/data.csv?time=2019,2025 ✅
An option that returns the nearest available time period in a dataset if the selected dates are outside of the range available.
| Value | Behaviour |
|---|---|
| none | Do not return any data if selected date is not covered (default) |
| latest | Return the latest available period if the select date is later |
| earliest | Return the earliest available period if the selected date is earlier |
| any | Return the earliest or latest period depending on which side the range the selected date falls |
Example: /api/v1/data.csv?time=2025&timeNearest=latest ☑️
Filter geographies by group (eg. "ltla") or GSS code (eg. "K02000001"). These filters can be combined as a comma-separated list.
Example: /api/v1/data.csv?geo=ltla,K02000001 ✅
Filter to only include geographies within a given parent area. Most likely to be used to filter for local authorities within a specific country (eg. "N92000002) or an English region (eg. "E12000001").
Example: /api/v1/data.csv?geo=ltla&geoExtent=N92000002 ✅
Filter to only include geographies within a given cluster. Requests should be in the format geoCluster={grouping}_{cluster}.
Example: /api/v1/data.csv?geoCluster=economic_a
Note: The geoCluster parameter ignores selected geoLevels (eg. rgn). However, it retains individually requested GSS codes even if they are not in the selected cluster.
Filter indicators for those that include a specific geographic area by its GSS code (eg. all datasets that include Norwich, E07000148). This is different to the geo parameter, which will filter out the data for other areas.
Example: /api/v1/data.csv?hasGeo=E07000148 ✅
Note: This filter is sensitive to the time filter, ensuring that the selected GSS code is present for the specific time period requested.
Filter an indicator on any dimension that is not geography or time. Can be a single value, a comma-separated list of values, or "all" (which is the default).
Example: /api/v1/data.csv?indicator=population-by-age-and-sex&dimension_sex=female&dimension_age=0-4,5-9 ✅
Note: This parameter will be ignored if the selected dimension does not exist for a particular indicator. You can look up the dimensions for an indicator and their possible values from the metadata endpoint.
To save data, area names are not included by default in responses. They can be added by setting the geoNames parameter to "true".
Example: /api/v1/data.csv?includeNames=true ✅
Some datasets include an observation-level status identifier to categorise missing/null values. These values can be included in the response (if available) by setting the includeStatus parameter to "true".
Example: /api/v1/data.csv?includeStatus=true ✅