Query a data set (GET)

Query a data set using a GET request, returning the filtered results.

Note that there is a POST variant of this endpoint which provides a more complete set of querying functionality. The GET variant is only recommended for initial exploratory testing or simple queries that do not need advanced functionality.

Unlike the POST variant, this endpoint does not allow condition clauses (and, or, not) and consequently cannot express more complex queries. Use the POST variant instead for these types of queries.

Indicators

The indicators query parameter is required and at least one indicator must be specified.

Each indicator should be a string containing the indicator ID e.g. headcount, enrolments.

Filters

The filters query parameter is used to filter by other filter options (not locations, geographic levels or time periods).

Each filter should be a string containing the required filter option ID e.g. z4FQE, DcQeg.

Geographic levels

The geographicLevels query parameter is used to filter results by geographic level.

The geographic levels are specified as codes, and can be one of the following:

EDA - English devolved area
INST - Institution
LA - Local authority
LAD - Local authority district
LEP - Local enterprise partnership
LSIP - Local skills improvement plan area
MCA - Mayoral combined authority
MAT - MAT
NAT - National
OA - Opportunity area
PA - Planning area
PCON - Parliamentary constituency
PROV - Provider
REG - Regional
RSC - RSC region
SCH - School
SPON - Sponsor
WARD - Ward

Locations

The locations query parameter is used to filter results by location.

The locations should be strings formatted like {level}|{property}|{value} where:

{level} is the location’s level code (e.g. NAT, REG, LA)
{property} is the name of the identifying property to match on (e.g. id,code,urn`)
{value} is the value for the property to match

An ID or a code can be used to identify a location, with the following differences:

IDs only match a single location
Codes may match multiple locations

Whilst codes are generally unique to a single location, they can be used for multiple locations. This may match more results than you expect so it’s recommended to use IDs where possible.

Examples

LA|code|E08000019 matches any local authority with code E08000019
REG|id|abcde matches any region with ID abcde
SCH|urn|140821 matches any school with URN 140821

Time periods

The timePeriods query parameter is used to filter results by time period.

The time periods should be strings formatted like {period}|{code} where:

period is the time period or range (e.g. 2020 or 2020/2021)
code is the code identifying the time period type (e.g. AY, CY, M1, W20)

The period should be a single year like 2020, or a range like 2020/2021. Currently, only years (or year ranges) are supported.

Some time period types span two years e.g. financial year part 2 (P2), or may fall in a latter year e.g. academic year summer term (T3). For these types, a singular year period like 2020 is considered as 2020/2021.

For example, a period value of 2020 is applicable to the following time periods:

2020 calendar year
2020/2021 academic year
2020/2021 financial year part 2 (October to March)
2020/2021 academic year’s summer term

If you wish to be more explicit, you may use a range for the period e.g. 2020/2021. However, a range cannot be used with time period types which only span a single year, for example, 2020/21 cannot be used with CY, M or W codes.

Examples

2020|AY is the 2020/21 academic year
2021|FY is the 2021/22 financial year
2020|T3 is the 2020/21 academic year’s summer term
2020|P2 is the 2020/21 financial year part 2 (October to March)
2020|CY is the 2020 calendar year
2020|W32 is 2020 week 32
2020/2021|AY is the 2020/21 academic year
2021/2022|FY is the 2021/22 financial year

Sorts

The sorts query parameter is used to sort the results.

Sorts are applied in the order they are provided and should be strings formatted like {field}|{direction} where:

field is the name of the field to sort e.g. time_period
direction is the direction to sort in e.g. ascending (Asc) or descending (Desc)

The field can be one of the following:

timePeriod to sort by time period
geographicLevel to sort by the geographic level of the data
location|{level} to sort by locations in a geographic level where {level} is the level code (e.g. REG, LA)
A filter ID (e.g. characteristic, school_type) to sort by the options in that filter
An indicator ID (e.g. sess_authorised, enrolments) to sort by the values in that indicator

Examples

timePeriod|Desc sorts by time period in descending order
geographicLevel|Asc sorts by geographic level in ascending order
location|REG|Asc sorts by regions in ascending order

The URL for this endpoint is:

GET https://dev.statistics.api.education.gov.uk/api/v{version}/data-sets/{dataSetId}/query

Parameters

Path parameters

The following parameters will need to be substituted into the URL path.

Parameter Type Required Description

Parameter	Type	Required	Description
`dataSetId`	string	true	The ID of the data set.
`version`	string	true	The requested API version Defaults to: `1.0`

dataSetId

string

true

The ID of the data set.

version

string

true

The requested API version

Defaults to: 1.0

Query parameters

Parameter	Type	Required	Description
`dataSetVersion`	string	false	The version of the data set to use e.g. 2.0, 1.1, etc.
`filters.in`	array (string)	false	Filter the results to have a filter option matching at least one of these IDs.
`filters.notIn`	array (string)	false	Filter the results to not have a filter option matching any of these IDs.
`filters.eq`	string	false	Filter the results to have a filter option matching this ID.
`filters.notEq`	string	false	Filter the results to not have a filter option matching this ID.
`geographicLevels.in`	array (GeographicLevelCode)	false	Filter the results to be in one of these geographic levels.
`geographicLevels.notIn`	array (GeographicLevelCode)	false	Filter the results to not be in one of these geographic levels.
`geographicLevels.eq`	GeographicLevelCode	false	Filter the results to be in this geographic level.
`geographicLevels.notEq`	GeographicLevelCode	false	Filter the results to not be in this geographic level.
`locations.eq`	string	false	Filter the results to be in this location.
`locations.notEq`	string	false	Filter the results to not be in this location.
`locations.in`	array (string)	false	Filter the results to be in one of these locations.
`locations.notIn`	array (string)	false	Filter the results not to be in one of these locations.
`timePeriods.eq`	string	false	Filter the results to be in this time period.
`timePeriods.notEq`	string	false	Filter the results to not be in this time period.
`timePeriods.in`	array (string)	false	Filter the results to be in one of these time periods.
`timePeriods.notIn`	array (string)	false	Filter the results to not be in one of these time periods.
`timePeriods.gt`	string	false	Filter the results to be in a time period that is chronologically greater than the one specified.
`timePeriods.gte`	string	false	Filter the results to be in a time period that is chronologically greater than or equal to the one specified.
`timePeriods.lt`	string	false	Filter the results to be in a time period that is chronologically less than the one specified.
`timePeriods.lte`	string	false	Filter the results to be in a time period that is chronologically less than or equal to the one specified.
`indicators`	array (string)	true	The IDs of indicators to return values for.
`sorts`	array (string)	false	The sorts to apply to the results. Sorts at the start of the list will be applied first. By default, results are sorted by time period in descending order.
`debug`	boolean	false	Enable debug mode. Results will be formatted with human-readable labels to assist in identification. This should not be enabled in a production environment.
`page`	integer	false	The page of results to fetch. Defaults to: `1` Validation constraints: Format: `int32` Minimum: `1`
`pageSize`	integer	false	The maximum number of results per page. Defaults to: `1000` Validation constraints: Format: `int32` Minimum: `1` Maximum: `10000`

Example request

To illustrate how to use this API endpoint, we have provided some samples below in various languages.

cURL
JavaScript
Python
R

cURL

curl -X GET https://dev.statistics.api.education.gov.uk/api/v{version}/data-sets/{dataSetId}/query

JavaScript

const url = 'https://dev.statistics.api.education.gov.uk/api/v{version}/data-sets/{dataSetId}/query';

const response = await fetch(url, {
  method: 'GET',
});

console.log(response.json());

Python

import requests

url = 'https://dev.statistics.api.education.gov.uk/api/v{version}/data-sets/{dataSetId}/query'

response = requests.get(url)

print(response.text)

R

library(httr)

url <- 'https://dev.statistics.api.education.gov.uk/api/v{version}/data-sets/{dataSetId}/query'

response <- httr::GET(url)

output <- content(response)

Responses

Status	Description	Media Type	Schema
200	The paginated list of query results	application/json	DataSetQueryPaginatedResultsViewModel
400	Bad Request	application/json	ValidationProblemViewModel
403	Forbidden	application/json	ProblemDetailsViewModel
404	Not Found	application/json	ProblemDetailsViewModel

Example successful response

{
  "paging": {
    "page": 1,
    "pageSize": 20,
    "totalResults": 60,
    "totalPages": 3
  },
  "results": [
    {
      "timePeriod": {
        "code": "AYQ1",
        "period": "2020/2021"
      },
      "geographicLevel": "NAT",
      "locations": {
        "<*>": "string"
      },
      "filters": {
        "<*>": "string"
      },
      "values": {
        "<*>": "string"
      }
    }
  ],
  "warnings": [
    {
      "message": "There are no results.",
      "path": "results",
      "code": "NoResults",
      "detail": {
        "total": 0
      }
    }
  ]
}