Skip to main content

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
criteria one of: false

The criteria to match.
indicators array (string) true

The IDs of indicators in the data set to return values for.

Validation constraints:

  • Minimum items: 1

Validation constraints for child items:

  • Maximum length: 40
  • Minimum length: 1
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: 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 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://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": {
            "level": "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": {
            "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://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": {
            "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

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": {
            "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
      }
    }
  ]
}