Technical specification

The OS Downloads API is a service that lets you automate the discovery and download of OS OpenData and data packages.

This technical specification explains the methods that you can use to call the OS Downloads API.

If you are not familiar with the OS Downloads API please read the overview documentation before proceeding.

OS Downloads API allows you to access information about available OS OpenData products and obtain product metadata as well as download links. The API also allows you to access information about your data packages, and to download any available data package versions. The API can be used to automate the retrieval and integration of OS data with your own systems.

Core concepts

This specification does not cover core concepts that apply to all Ordnance Survey APIs.

Please read the following pages to learn more about OS API core concepts:

• Authentication

• Error codes

• Rate-limiting policy

API reference

To use the:

• OS OpenData parts of this API you do not require an API Key.

• Data package endpoints (premium products) you need to use an API Key (or OAuth 2 access token).

Since the content of the API may change as products are changed, added to or removed, you should use the methods listed to get the most current list of content available.

The OS Downloads API provides different methods for downloading OS OpenData and data packages (premium data products).

OS OpenData

Operations providing access to OS OpenData products:

Returns a list of the OS OpenData products that are available to download.

GEThttps://api.os.uk/downloads/v1/products

Query parameters

Response

200

Successful response.

Body

application/json

id*string

name*string

description*array of string

version*string

Pattern: ^/d{4}-/d{2}$

url*string

documentationUrlstring

areasarray of Area (enum)

dataStructuresarray of enum

categorystring

formatsarray of Format (object)

imageCountinteger

imageTemplatestring

downloadsUrlstring (uri)

warningstring

Request

JavaScriptCurlPython

const response = await fetch('https://api.os.uk/downloads/v1/products', {
    method: 'GET',
    headers: {},
});
const data = await response.json();

Response

200

[
  {
    "id": "text",
    "name": "text",
    "description": [
      "text"
    ],
    "version": "text",
    "url": "text",
    "documentationUrl": "text",
    "areas": [
      "GB"
    ],
    "dataStructures": [
      "Raster"
    ],
    "category": "text",
    "formats": [
      {
        "format": "text",
        "subformat": "text"
      }
    ],
    "imageCount": 0,
    "imageTemplate": "text",
    "downloadsUrl": "https://example.com",
    "warning": "text"
  }
]

Returns details about a specific OS OpenData product.

GEThttps://api.os.uk/downloads/v1/products/{productId}

Path parameters

productId*string

The id of the product.

Response

200404

Successful response.

Body

application/json

id*string

name*string

description*array of string

version*string

Pattern: ^/d{4}-/d{2}$

url*string

documentationUrlstring

areasarray of Area (enum)

dataStructuresarray of enum

categorystring

formatsarray of Format (object)

imageCountinteger

imageTemplatestring

downloadsUrlstring (uri)

warningstring

Request

JavaScriptCurlPython

const response = await fetch('https://api.os.uk/downloads/v1/products/{productId}', {
    method: 'GET',
    headers: {},
});
const data = await response.json();

Response

200404

{
  "id": "text",
  "name": "text",
  "description": [
    "text"
  ],
  "version": "text",
  "url": "text",
  "documentationUrl": "text",
  "areas": [
    "GB"
  ],
  "dataStructures": [
    "Raster"
  ],
  "category": "text",
  "formats": [
    {
      "format": "text",
      "subformat": "text"
    }
  ],
  "imageCount": 0,
  "imageTemplate": "text",
  "downloadsUrl": "https://example.com",
  "warning": "text"
}

Returns a list of downloads for a specific OS OpenData product, or redirects to the actual download if requested.

GEThttps://api.os.uk/downloads/v1/products/{productId}/downloads

Path parameters

productId*string

The id of the product.

Query parameters

Response

200307404

Successful response.

Body

application/json

url*string (uri)

Getting this URL will return a HTTP redirect to the actual data.

fileName*string

The name of the file.

Example: "data.zip"

sizeinteger

The file size, in bytes.

Example: 1234

md5string

A MD5 checksum of the file data. This can be used to verify the integrity of the data once you have downloaded it.

Example: "2f9dd13abd56140afa3b5621e8864f59"

area*Area (enum)

This describes the geographical area that a download covers. GB is all of Great Britain, while codes like 'HP' cover National Grid Reference squares.

GBHPHTHUHWHXHYHZNANBNCNDNFNGNHNJNKNLNMNNNONRNSNTNUNWNXNYNZOVSDSETASHSJSKTFTGSMSNSOSPTLTMSRSSSTSUTQTRSVSWSXSYSZTV

format*string

This describes the format of the data.

Example: "GML"

subformatstring

This describes the subformat of the data.

Example: "3"

Request

JavaScriptCurlPython

const response = await fetch('https://api.os.uk/downloads/v1/products/{productId}/downloads', {
    method: 'GET',
    headers: {},
});
const data = await response.json();

Response

200307404

[
  {
    "url": "https://example.com",
    "fileName": "data.zip",
    "size": 1234,
    "md5": "2f9dd13abd56140afa3b5621e8864f59",
    "area": "GB",
    "format": "GML",
    "subformat": "3"
  }
]

Returns a HTTP redirect, pointing to thumbnail images for the specified OS OpenData product.

GEThttps://api.os.uk/downloads/v1/products/{productId}/images/{index}

Path parameters

productId*string

The id of the product.

index*integer

The index of the image to be retrieved. Valid values are from 0 to (Product.imageCount-1).

Query parameters

Response

200307404

Successful response.

Body

image/jpeg

string (binary)

Request

JavaScriptCurlPython

const response = await fetch('https://api.os.uk/downloads/v1/products/{productId}/images/{index}', {
    method: 'GET',
    headers: {},
});
const data = await response.json();

Response

200404

binary

Data Packages

Operations providing access to data packages.

To access data packages you must supply a valid API key or OAuth 2 access token.

List the data packages that are available to you.

GEThttps://api.os.uk/downloads/v1/dataPackages

Authorization

OAuth2APIKeyQueryAPIKeyHeader

Response

200401

A list of data packages.

Body

application/json

id*string

Example: "0040046952"

name*string

Example: "Southampton Addresses"

url*string (uri)

Example: "https://api.os.uk/downloads/v1/dataPackages/0040046952"

createdOn*string (date)

Example: "2021-01-20"

productId*string

Example: "ABPOSTSLA"

productName*string

Example: "AddressBase"

versions*array of DataPackageVersionSummary (object)

Request

JavaScriptCurlPython

const response = await fetch('https://api.os.uk/downloads/v1/dataPackages', {
    method: 'GET',
    headers: {},
});
const data = await response.json();

Response

200401

[
  {
    "id": "0040046952",
    "name": "Southampton Addresses",
    "url": "https://api.os.uk/downloads/v1/dataPackages/0040046952",
    "createdOn": "2021-01-20",
    "productId": "ABPOSTSLA",
    "productName": "AddressBase",
    "versions": [
      {
        "id": "110012",
        "url": "https://api.os.uk/downloads/v1/dataPackages/0040046952/versions/110012",
        "createdOn": "2021-04-01",
        "reason": "INITIAL",
        "supplyType": "FULL",
        "productVersion": "E37 December 2015 Update",
        "format": "CSV",
        "dataPackageUrl": "https://api.os.uk/downloads/v1/dataPackages/0040046952"
      }
    ]
  }
]

Get a specific data package.

GEThttps://api.os.uk/downloads/v1/dataPackages/{dataPackageId}

Authorization

OAuth2APIKeyQueryAPIKeyHeader

Path parameters

dataPackageId*string

The id of the data package.

Response

200401404

A data package.

Body

application/json

id*string

Example: "0040046952"

name*string

Example: "Southampton Addresses"

url*string (uri)

Example: "https://api.os.uk/downloads/v1/dataPackages/0040046952"

createdOn*string (date)

Example: "2021-01-20"

productId*string

Example: "ABPOSTSLA"

productName*string

Example: "AddressBase"

versions*array of DataPackageVersionSummary (object)

Request

JavaScriptCurlPython

const response = await fetch('https://api.os.uk/downloads/v1/dataPackages/{dataPackageId}', {
    method: 'GET',
    headers: {},
});
const data = await response.json();

Response

200401404

{
  "id": "0040046952",
  "name": "Southampton Addresses",
  "url": "https://api.os.uk/downloads/v1/dataPackages/0040046952",
  "createdOn": "2021-01-20",
  "productId": "ABPOSTSLA",
  "productName": "AddressBase",
  "versions": [
    {
      "id": "110012",
      "url": "https://api.os.uk/downloads/v1/dataPackages/0040046952/versions/110012",
      "createdOn": "2021-04-01",
      "reason": "INITIAL",
      "supplyType": "FULL",
      "productVersion": "E37 December 2015 Update",
      "format": "CSV",
      "dataPackageUrl": "https://api.os.uk/downloads/v1/dataPackages/0040046952"
    }
  ]
}

Get the list of versions for a specific data package.

GEThttps://api.os.uk/downloads/v1/dataPackages/{dataPackageId}/versions

Authorization

OAuth2APIKeyQueryAPIKeyHeader

Path parameters

dataPackageId*string

The id of the data package.

Response

200401404

A list of data package versions.

Body

application/json

id*string

Example: "110012"

url*string (uri)

Example: "https://api.os.uk/downloads/v1/dataPackages/0040046952/versions/110012"

createdOn*string (date)

Example: "2021-04-01"

reason*enum

INITIALUPDATEEXPANSIONRESUPPLYONLINE_ORDER

supplyType*enum

FULLCOU

productVersion*string

Example: "E37 December 2015 Update"

formatstring

Example: "CSV"

dataPackageUrlstring (uri)

Example: "https://api.os.uk/downloads/v1/dataPackages/0040046952"

Request

JavaScriptCurlPython

const response = await fetch('https://api.os.uk/downloads/v1/dataPackages/{dataPackageId}/versions', {
    method: 'GET',
    headers: {},
});
const data = await response.json();

Response

200401404

[
  {
    "id": "110012",
    "url": "https://api.os.uk/downloads/v1/dataPackages/0040046952/versions/110012",
    "createdOn": "2021-04-01",
    "reason": "INITIAL",
    "supplyType": "FULL",
    "productVersion": "E37 December 2015 Update",
    "format": "CSV",
    "dataPackageUrl": "https://api.os.uk/downloads/v1/dataPackages/0040046952"
  }
]

Get a specific data package version, including details of the files that are available to download.

GEThttps://api.os.uk/downloads/v1/dataPackages/{dataPackageId}/versions/{versionId}

Authorization

OAuth2APIKeyQueryAPIKeyHeader

Path parameters

dataPackageId*string

The id of the data package.

versionId*string

The id of the data package version, or the string 'latest'.

Response

200401404

A data package version, including download details.

Body

application/json

id*string

Example: "110012"

url*string (uri)

Example: "https://api.os.uk/downloads/v1/dataPackages/0040046952/versions/110012"

createdOn*string (date)

Example: "2021-04-01"

reason*enum

INITIALUPDATEEXPANSIONRESUPPLYONLINE_ORDER

supplyType*enum

FULLCOU

productVersion*string

Example: "E37 December 2015 Update"

formatstring

Example: "CSV"

dataPackageUrlstring (uri)

Example: "https://api.os.uk/downloads/v1/dataPackages/0040046952"

nextVersionUrlstring (uri)

Only populated if there is a newer version of the data package.

Example: "https://api.os.uk/downloads/v1/dataPackages/0040046952/versions/110013"

previousVersionUrlstring (uri)

Only populated if there is an older version of the data package.

Example: "https://api.os.uk/downloads/v1/dataPackages/0040046952/versions/110011"

downloads*array of Download (object)

Request

JavaScriptCurlPython

const response = await fetch('https://api.os.uk/downloads/v1/dataPackages/{dataPackageId}/versions/{versionId}', {
    method: 'GET',
    headers: {},
});
const data = await response.json();

Response

200401404

{
  "id": "110012",
  "url": "https://api.os.uk/downloads/v1/dataPackages/0040046952/versions/110012",
  "createdOn": "2021-04-01",
  "reason": "INITIAL",
  "supplyType": "FULL",
  "productVersion": "E37 December 2015 Update",
  "format": "CSV",
  "dataPackageUrl": "https://api.os.uk/downloads/v1/dataPackages/0040046952",
  "nextVersionUrl": "https://api.os.uk/downloads/v1/dataPackages/0040046952/versions/110013",
  "previousVersionUrl": "https://api.os.uk/downloads/v1/dataPackages/0040046952/versions/110011",
  "downloads": [
    {
      "url": "https://example.com",
      "fileName": "data.zip",
      "size": 1234,
      "md5": "2f9dd13abd56140afa3b5621e8864f59"
    }
  ]
}

Get a specific file from a data package version.

GEThttps://api.os.uk/downloads/v1/dataPackages/{dataPackageId}/versions/{versionId}/downloads

Authorization

OAuth2APIKeyQueryAPIKeyHeader

Path parameters

dataPackageId*string

The id of the data package.

versionId*string

The id of the data package version.

Query parameters

Response

307401404

A redirect to the actual file data.

Headers

Request

JavaScriptCurlPython

const response = await fetch('https://api.os.uk/downloads/v1/dataPackages/{dataPackageId}/versions/{versionId}/downloads?fileName=text', {
    method: 'GET',
    headers: {},
});
const data = await response.json();

Response

401404

{
  "message": "Invalid APIKey"
}