Introduction
The Office for National Statistics API makes datasets and other data available programmatically using HTTP. It allows you to filter datasets and directly access specific data points.
The API is available at https://api.beta.ons.gov.uk/v1
The API is open and unrestricted - no API keys are required, so you can start using it immediately.
This API is currently in Beta and still being developed. Please be aware that as a result of this there may occasionally be breaking changes as we enhance functionality and respond to feedback.
Getting data from ONS Beta API
Requesting data
Observation level data is provided in JSON through GET requests to the ‘Explore our data’ service. This allows querying of a single observation/value by providing one option per dimension, but will also allow one of these dimensions to be a ‘wildcard’ and return all values for this dimension.
Guide to requesting specific observation
Filtering a dataset
For more complicated queries the ‘Filter a dataset’ service will be the best approach. This allows any combination of dimensions to be requested using POST and will return the data as CSV and XLSX.
Rate limiting
The ONS API applies rate limiting to ensure a high quality service is delivered to all users and to protect client applications from unexpected loops.
The following rate limits have been implemented:
120 requests per 10 seconds
200 requests per 1 minute
If you exceed these limits the API will return a 429 Too Many Requests HTTP status code and a Retry-After header containing the number of seconds until you may try your request again.
Terminology
Descriptions for some terms used within this API.
Dataset
A grouping of data (editions) with shared dimensions, for example Sex, Age and Geography, and all published history of this group of data. The options in these dimensions can change over time leading to separate editions. For example: Population Estimates for UK, England and Wales, Scotland and Northern Ireland
Edition
A subset of the dataset representing a specific time period. For some datasets this edition can contain all time periods (all historical data). The latest version of this is displayed by default. For example: Population Estimates for UK, England and Wales, Scotland and Northern Ireland Mid-2016
Version
A specific instance of the edition at a point in time. New versions can be published as a result of corrections, revisions or new data becoming available.
Are these definitions helpful? Are there other terms we need to explain? Let us know