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.

The URL for this endpoint is:

POST 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
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.

Request body

The request body is described by the DataSetQueryRequest schema which contains the following parameters:

Name	Type	Required	Description

Example request body

{
  "criteria": {
    "and": [
      {
        "filters": {
          "eq": "pVAkV"
        }
      },
      {
        "locations": {
          "eq": "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://dev.statistics.api.education.gov.uk/api/v{version}/data-sets/{dataSetId}/query \
 -H 'Content-Type: application/json' \
 -d '{
  "criteria": {
    "and": [
      {
        "filters": {
          "eq": "pVAkV"
        }
      },
      {
        "locations": {
          "eq": "LA|code|E08000019"
        }
      }
    ]
  },
  "indicators": [
    "C2ySJ",
    "q4X3J"
  ],
  "sorts": [
    {
      "field": "timePeriod",
      "direction": "Asc"
    }
  ],
  "debug": true,
  "page": 1,
  "pageSize": 1000
}'

JavaScript

const url = 'https://dev.statistics.api.education.gov.uk/api/v{version}/data-sets/{dataSetId}/query';
const headers = {
  'Content-Type': 'application/json'
},
const body = {
  "criteria": {
    "and": [
      {
        "filters": {
          "eq": "pVAkV"
        }
      },
      {
        "locations": {
          "eq": "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://dev.statistics.api.education.gov.uk/api/v{version}/data-sets/{dataSetId}/query'
headers = {
  "Content-Type": "application/json",
}
data = '{
  "criteria": {
    "and": [
      {
        "filters": {
          "eq": "pVAkV"
        }
      },
      {
        "locations": {
          "eq": "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

library(httr)

url <- 'https://dev.statistics.api.education.gov.uk/api/v{version}/data-sets/{dataSetId}/query'
body <- '{
  "criteria": {
    "and": [
      {
        "filters": {
          "eq": "pVAkV"
        }
      },
      {
        "locations": {
          "eq": "LA|code|E08000019"
        }
      }
    ]
  },
  "indicators": [
    "C2ySJ",
    "q4X3J"
  ],
  "sorts": [
    {
      "field": "timePeriod",
      "direction": "Asc"
    }
  ],
  "debug": true,
  "page": 1,
  "pageSize": 1000
}'

response <- httr::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": {
        "<*>": "string"
      },
      "filters": {
        "<*>": "string"
      },
      "values": {
        "<*>": "string"
      }
    }
  ],
  "warnings": [
    {
      "message": "There are no results.",
      "path": "results",
      "code": "NoResults",
      "detail": {
        "total": 0
      }
    }
  ]
}