Using the OS Downloads API
Last updated
Was this helpful?
Last updated
Was this helpful?
OS Downloads API is a service, not new data, and provides a mechanism to download OS data. It allows you to download OS OpenData and OS Premium Data outside of OS Data Hub.
Released October 2021 the service uses a URL to perform requests and retrieve the datasets.
It is available to all PSGA members and requires an OS Data Hub account
Data Packages is the generic term for any order that you have created in the ‘Download’ section of the OS Data Hub.
They are displayed by:
Your reference (the name you gave it on creation)
Data Package ID (auto generated but persists)
Date (date the package was created)
Product Name (name of the OS Product)
Status (whether a download is available)
You will need to have created your data packages before you can download them via the OS Downloads API.
Create a new project or open an existing project in the API Dashboard tab.​
Click ‘Add API’ button.​
Click on the ‘Add to Project’ button for the OS Downloads API to add it to this project.​
Your OS Downloads API Key will be generated and listed in your API list.​
Should your API Key ever be compromised, or you wish prevent access (e.g. a contractor) you can click ‘Actions’ near the project name and ‘Regenerate API Key’ to create a new API Key.​
For OS Open data and Premium data packages you can:
Discover which datasets are available.​
Find the latest data available.​
Automate the download.​
Request the metadata.​
You won’t be able to:​
Access previous releases of OS OpenData datasets.​
Use it to create new recipes or data packages.​
Request alterations to existing data packages.
JSON (JavaScript Object Notation) is a format for representing data in a way that can be easily read and processed by computers.
JSON is often used to exchange data between a client and a server.
It is lightweight and widely supported
Comprised of keys and values – a bit like a dictionary In its simplest form it can be used in a web browser
This looks at the OS DataHub and the Downloads API to compare what you will see in each
On the OS DataHub your packages will look as they do on the left: https://osdatahub.os.uk/downloads/packages
On the OS Downloads API the same packages will look as they do on the right: https://api.os.uk/downloads/v1/dataPackages?key=(APIKey)
Adding specific parameters into your API call will allow you to download specific versions of the data:
https://api.os.uk/downloads/v1/dataPackages/(PackageNumber)/versions/latest?key=(APIKey)
On the OS Data Hub choosing versions looks like the image below...
Using the OS Downloads API choosing versions looks more like the following image, but is displaying the same information as above.
Having selected a version, you can further modify the API call to download specific files using a url similar to this one:
https://api.os.uk/downloads/v1/dataPackages/(PackageNumber)/versions/(version)/downloads?fileName=ad_gb_builtaddress.zip&key=(APIKey)
On the OS DataHub, having chosen a version you are presented with a set of download links, as shown here on the left. On the right are the same links but via the OS Downloads API:
OS Downloads API can be used to automate OS data downloads
Data is kept up to date, so the data currency is the best that it can be
This can be integrated with data loaders to fully automate the whole data update process
The process is reliable as it always runs the same way
Efficient by massively reducing officer time in handling data updates
It can be run out of hours making updates convenient
Getting Started Guide:
Technical Specification:
OS Data Hub:
Automate downloads and remove manual handling
Currency
Always have the most up-to-date data
Integrate
Join to data loading to fully automate your data updates
Reliable
Reduce/eliminate download and loading errors
Efficiency
Save time and resources by not manually handling
Convenient
Can be scheduled to run out of hours or at any time
