Beta API: An introduction
As you may have already seen we recently launched our separate API and developer site in Beta. I wanted to build on Andy’s introduction post and talk a bit about the structure of the data available in the API and give some simple examples.
Anyone familiar with the breadth of content that ONS publish will notice quite quickly that not all of it is currently available from the API. Expanding this is the plan over time, and my main focus as part of our Customise My Data (formerly Data Discovery) developments will be just that.
The API currently focuses around the data we do have already available in a structured format, specifically our economic time series. These are already available from the current site-based API by adding ‘/data’ to the end of the page URL – for RPI the individual page for this series is; https://www.ons.gov.uk/economy/inflationandpriceindices/timeseries/czbh/mm23 and the data for this is available in JSON from https://www.ons.gov.uk/economy/inflationandpriceindices/timeseries/czbh/mm23/data.
This method of making the data available has some benefits but also has some issues, in particular that, should the structure of the website change, this URL would too and also you need to know where on the site the series you want is before you can use it.
To access the data itself from the API you will need to use these individual time series. In addition to this you will need to decide which dataset version of the series you want. For a lot of series they only appear in one dataset but some, particularly those around GDP can be published in a number of datasets.
Finding a series
You can find a list of all time series in a specific dataset using the following endpoint, so if you are familiar with these or know the broad subject area you are interested in this is probably the place to start.
Here is the CPI example;
https://api.ons.gov.uk/dataset/mm23/timeseries
You can also use our separate search to identify which time series you want, for example; https://api.ons.gov.uk/search?q=rpi
This will provide details of what is available, both datasets and time series, and once you know what you need, take a note of the field labelled ‘cdid’. This will give you the series identifier of that specific series.
These IDs are also published alongside these series on the website so this is another alternative route to finding them.
Getting data with a CDID (series identifier)
Once you have your series ID you can use the following endpoint to access information about that series;
https://api.ons.gov.uk/timeseries/czbh
This endpoint will also give details of the dataset, or datasets, that series is published as part of. You can see the following example is published in 5 separate datasets (look at ‘datasetId’);
https://api.ons.gov.uk/timeseries/abmi
You can then access the detail for this variation of the data by including this in your request, for example;
https://api.ons.gov.uk/timeseries/abmi/dataset/ukea
The data for this series is then accessed the same way as on the website, with the addition of ‘/data’, as shown here;
https://api.ons.gov.uk/timeseries/abmi/dataset/ukea/data
This API and developer site have been put out in Beta to gather feedback to inform future developments, particularly our Customise my Data developments which will be looking to build on this with much more ONS data and metadata.
If you have any thoughts or comments on this let me know on twitter @robchamberspfc, on this blog post or to the team @ONSdigital