Using the OS Downloads API

What is the OS Downloads API?

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

Why use OS Downloads API

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

What are Data Packages?

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)

Data Packages in the OS Data Hub

You will need to have created your data packages before you can download them via the OS Downloads API.

How to get your API Key?

• 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.​

What can you do with the API?

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

OS Downloads API get capabilities

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.

How does it work?

• 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

What data packages do I have?

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)

The entry highlighted in pink on the OS DataHub is the same as the one highlighted on the Downloads API

The entry highlighted in pink on the Downloads API is the same as the one highlighted on the OS DataHub

How do I get my latest data package?

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

OS DataHub with the option to choose versions highlighted

OS Downloads API with the version information highlighted

Using the OS Downloads API choosing versions looks more like the following image, but is displaying the same information as above.

How do download that package?

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:

Download links on OS DataHub

The same download links via the OS Downloads API

Summary

• 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

Resources

Getting Started Guide: https://docs.os.uk/os-apis/accessing-os-apis/os-downloads-api/getting-started

Technical Specification: https://docs.os.uk/os-apis/accessing-os-apis/os-downloads-api/technical-specification

OS Data Hub: https://osdatahub.os.uk/