# 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

<table data-view="cards"><thead><tr><th></th><th></th><th></th></tr></thead><tbody><tr><td><mark style="color:red;"><strong>Automate</strong></mark> downloads and remove manual handling</td><td></td><td></td></tr><tr><td><mark style="color:red;"><strong>Currency</strong></mark></td><td>Always have the most up-to-date data</td><td></td></tr><tr><td><mark style="color:red;"><strong>Integrate</strong></mark></td><td>Join to data loading to fully automate your data updates</td><td></td></tr><tr><td><mark style="color:red;"><strong>Reliable</strong></mark></td><td>Reduce/eliminate download and loading errors</td><td></td></tr><tr><td><mark style="color:red;"><strong>Efficiency</strong></mark></td><td>Save time and resources by not manually handling</td><td></td></tr><tr><td><mark style="color:red;"><strong>Convenient</strong></mark></td><td>Can be scheduled to run out of hours or at any time</td><td></td></tr></tbody></table>

## 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)

<figure><img src="/files/ZXEwKTEbt3aocEtai09h" alt="Data Packages in the OS Data Hub"><figcaption><p>Data Packages in the OS Data Hub</p></figcaption></figure>

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

<figure><img src="/files/ody3dXxbVcqiv4VSFT3l" alt="Add API to the Project window" width="428"><figcaption></figcaption></figure>

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

<figure><img src="/files/qj9KoynvBxZJmyYUCtuS" alt=""><figcaption></figcaption></figure>

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

<figure><img src="/files/ccKFwQzvwJfPP5OeId1h" alt="OS Downloads API get capabilities image"><figcaption><p>OS Downloads API get capabilities</p></figcaption></figure>

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

<figure><img src="/files/aqrKl7uWGlVCzl3SMuPf" alt="Image of the breakdown of the json entry into Keys and Values"><figcaption></figcaption></figure>

## 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: <mark style="color:blue;"><https://osdatahub.os.uk/downloads/packages></mark>

On the OS Downloads API the same packages will look as they do on the right: <mark style="color:blue;"><https://api.os.uk/downloads/v1/dataPackages?key=(></mark><mark style="color:red;">APIKey</mark><mark style="color:blue;">)</mark>

<div><figure><img src="/files/A9nLScFlN9Clynm25rLX" alt="Image of data packages in the OS DataHub"><figcaption><p>The entry highlighted in pink on the OS DataHub is the same as the one highlighted on the Downloads API</p></figcaption></figure> <figure><img src="/files/AjtInejevPE2y8rPYwbR" alt="Image of data packages in the OS Downloads API"><figcaption><p>The entry highlighted in pink on the Downloads API is the same as the one highlighted on the OS DataHub</p></figcaption></figure></div>

## 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:

<mark style="color:blue;"><https://api.os.uk/downloads/v1/dataPackages/></mark><mark style="color:red;">(PackageNumber)</mark><mark style="color:blue;">/versions/</mark><mark style="color:blue;">**latest**</mark><mark style="color:blue;">?key=</mark><mark style="color:red;">(APIKey)</mark>

On the OS Data Hub choosing versions looks like the image below\...

<div><figure><img src="/files/16fQ1y5nCizFvBxnwz7o" alt="OS DataHub with the option to choose versions highlighted"><figcaption><p>OS DataHub with the option to choose versions highlighted</p></figcaption></figure> <figure><img src="/files/X6QB7EQ6hY9vx72rQZ3H" alt="OS Downloads API with the version information highlighted"><figcaption><p>OS Downloads API with the version information highlighted</p></figcaption></figure></div>

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:

<mark style="color:blue;"><https://api.os.uk/downloads/v1/dataPackages/></mark><mark style="color:red;">(PackageNumber)</mark><mark style="color:blue;">/versions/</mark><mark style="color:red;">(version)</mark><mark style="color:blue;">/downloads?fileName=</mark><mark style="color:red;">ad\_gb\_builtaddress.zip</mark><mark style="color:blue;">\&key=</mark><mark style="color:red;">(APIKey)</mark>

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:

<div><figure><img src="/files/cP8Iq7p8SVwtSzt9HlHp" alt=""><figcaption><p>Download links on OS DataHub</p></figcaption></figure> <figure><img src="/files/FEVjwRDFDHpwmaq5ZYn0" alt="The same download links via the OS Downloads API"><figcaption><p>The same download links via the OS Downloads API</p></figcaption></figure></div>

## Summary

* OS Downloads API can be used to <mark style="color:green;">automate</mark> OS data downloads
* Data is kept up to date, so the data <mark style="color:green;">currency</mark> is the best that it can be
* This can be <mark style="color:green;">integrated</mark> with data loaders to fully automate the whole data update process
* The process is <mark style="color:green;">reliable</mark> as it always runs the same way
* <mark style="color:green;">Efficient</mark> by massively reducing officer time in handling data updates
* It can be run out of hours making updates <mark style="color:green;">convenient</mark>

## 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/>


---

# Agent Instructions: Querying This Documentation

If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter:

```
GET https://docs.os.uk/more-than-maps/using-the-os-downloads-api.md?ask=<question>
```

The question should be specific, self-contained, and written in natural language.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.