Query a data set (POST)
Query a data set using a POST request, returning the filtered results.
Note that for simpler queries or exploratory testing, there is also GET variant of this endpoint only handles a smaller subset of querying functionality. However, for most use-cases, this endpoint is recommended as it provides the complete set of functionality.
Unlike the GET endpoint, the POST endpoint allows condition criteria (and, or, not)
and consequently can express more complex queries.
A POST request without a body will return a paginated set of unfiltered results and will include
values for all indicators.
A Content-Type request header of application/json is required.
The URL for this endpoint is:
POST https://api.education.gov.uk/statistics/v1/data-sets/{dataSetId}/query
Parameters
Path parameters
The following parameters will need to be substituted into the URL path.
| Parameter | Type | Required | Description |
|---|---|---|---|
dataSetId |
string | true |
The ID of the data set. |
Query parameters
| Parameter | Type | Required | Description |
|---|---|---|---|
dataSetVersion |
string | false |
The data set version e.g. 1.0, 1.1, 2.0, etc.
Wildcard versions are supported. For example, |
Request body
The request body is described by the DataSetQueryRequest schema which contains the following parameters:
| Name | Type | Required | Description |
|---|---|---|---|
criteria |
one of: | false |
The criteria to match. |
indicators |
array (string) | true |
The IDs of indicators to return values for. Omitting this parameter will return values for all indicators. Validation constraints for child items:
|
sorts |
array (DataSetQuerySort) | false |
The sorts to sort the results by. 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: Validation constraints:
|
pageSize |
integer | false |
The maximum number of results per page. Defaults to: Validation constraints:
|
Example request body
{
"criteria": {
"and": [
{
"filters": {
"eq": "pVAkV"
}
},
{
"locations": {
"eq": {
"level": "LA",
"code": "E08000019"
}
}
}
]
},
"indicators": [
"C2ySJ",
"q4X3J"
],
"sorts": [
{
"field": "timePeriod",
"direction": "Asc"
}
],
"debug": true,
"page": 1,
"pageSize": 1000
}
Example request
To illustrate how to use this API endpoint, we have provided some samples below in various languages.
cURL
curl -X POST https://api.education.gov.uk/statistics/v1/data-sets/{dataSetId}/query \
-H 'Content-Type: application/json' \
-d '{
"criteria": {
"and": [
{
"filters": {
"eq": "pVAkV"
}
},
{
"locations": {
"eq": {
"level": "LA",
"code": "E08000019"
}
}
}
]
},
"indicators": [
"C2ySJ",
"q4X3J"
],
"sorts": [
{
"field": "timePeriod",
"direction": "Asc"
}
],
"debug": true,
"page": 1,
"pageSize": 1000
}'
JavaScript
const url = 'https://api.education.gov.uk/statistics/v1/data-sets/{dataSetId}/query';
const headers = {
'Content-Type': 'application/json'
};
const body = {
"criteria": {
"and": [
{
"filters": {
"eq": "pVAkV"
}
},
{
"locations": {
"eq": {
"level": "LA",
"code": "E08000019"
}
}
}
]
},
"indicators": [
"C2ySJ",
"q4X3J"
],
"sorts": [
{
"field": "timePeriod",
"direction": "Asc"
}
],
"debug": true,
"page": 1,
"pageSize": 1000
};
const response = await fetch(url, {
method: 'POST',
headers,
body: JSON.stringify(body)
});
console.log(response.json());
Python
import requests
url = 'https://api.education.gov.uk/statistics/v1/data-sets/{dataSetId}/query'
headers = {
'Content-Type': 'application/json'
}
data = '''{
"criteria": {
"and": [
{
"filters": {
"eq": "pVAkV"
}
},
{
"locations": {
"eq": {
"level": "LA",
"code": "E08000019"
}
}
}
]
},
"indicators": [
"C2ySJ",
"q4X3J"
],
"sorts": [
{
"field": "timePeriod",
"direction": "Asc"
}
],
"debug": true,
"page": 1,
"pageSize": 1000
}'''
response = requests.post(url, headers=headers, data=data)
print(response.text)
R
# Look at the eesyapi package on GitHub for helper functions
# - https://github.com/dfe-analytical-services/eesyapi.R
# Example without the eesyapi package
library(httr)
url <- "https://api.education.gov.uk/statistics/v1/data-sets/{dataSetId}/query"
body <- "{
"criteria": {
"and": [
{
"filters": {
"eq": "pVAkV"
}
},
{
"locations": {
"eq": {
"level": "LA",
"code": "E08000019"
}
}
}
]
},
"indicators": [
"C2ySJ",
"q4X3J"
],
"sorts": [
{
"field": "timePeriod",
"direction": "Asc"
}
],
"debug": true,
"page": 1,
"pageSize": 1000
}"
response <- POST(
url,
body = body,
encode = "json",
content_type("application/json")
)
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": {
"NAT": "04bTr",
"REG": "4veOu",
"LA": "owqlK"
},
"filters": {
"ups2K": "n0WqP",
"j51wV": "AnZsi",
"hAkBQ": "dvB4z"
},
"values": {
"wLcft": "23593018",
"4S8Ou": "50.342",
"9kVFg": "25369172"
}
}
],
"warnings": [
{
"message": "There are no results.",
"path": "results",
"code": "NoResults",
"detail": {
"total": 0
}
}
]
}