Skip to main content

Data API

The Department for International Trade Data API supplies datasets via HTTPS.

  • Datasets are versioned
  • Each dataset version is immutable
  • Metadata for each dataset version is available as HTML or CSVW (CSV on the Web)
  • Columns and rows can be filtered using the S3 Select query language
  • Data is supplied as JSON or CSV
  • Authentication is not required

The source code for the Data API is available in its GitHub repository.

Base URL

All requests to this API should be prefixed with the following URL:

https://data.api.trade.gov.uk

Concepts

The function of the Data API is to supply datasets. A dataset has one or more immutable versions, and each version has one or more tables.

All the data in a version can be accessed by the GET data in a version endpoint, or the data in a single table of a version can be access by the GET data in a table endpoint.

Common parameters

Several parameters are applicable to multiple API endpoints.

Name Description
dataset A human-readable identifier of the dataset, e.g. uk-tariff-2021-01-01
version A version in the format vX.Y.Z, where X.Y.Z is the Semver 2.0 version of the dataset, e.g. v2.1.0
table A human-readable table name, e.g. commodities

API Endpoints

GET list of datasets

GET /v1/datasets

Query string parameters

Name Description
format (required) The requested output format. In all cases, this must be json

Example

Request
curl -X GET https://data.api.trade.gov.uk/v1/datasets?format=json
Response
Status: 200 OK
{
    "datasets": [
        {"id": "market-barriers"}, {"id": "uk-tariff-2021-01-01"}
    ]
}

GET list of versions of a dataset

GET /v1/datasets/:dataset/versions

Query string parameters

Name Description
format (required) The requested output format. In all cases, this must be json

Example

Request
curl -X GET https://data.api.trade.gov.uk/v1/datasets/uk-tariff-2021-01-01/versions?format=json
Response
Status: 200 OK
{
    "versions": [
        {"id": "v2.1.2"}, {"id": "v2.1.0"}
    ]
}

GET list of tables in a version

GET /v1/datasets/:dataset/versions/:version/tables

Query string parameters

Name Description
format (required) The requested output format. In all cases, this must be json

Example for specific version

Request
curl -X GET https://data.api.trade.gov.uk/v1/datasets/uk-tariff-2021-01-01/versions/v2.1.0/tables?format=json
Response
Status: 200 OK
{
    "tables": [
        {"id": "commodities"},
        {"id": "measures-as-defined"},
        {"id": "measures-on-declarable-commodities"}
    ]
}

Example for latest version

Replacing the version string with the word latest will result in a redirect to the latest version of the dataset.

Request
curl -X GET https://data.api.trade.gov.uk/v1/datasets/uk-tariff-2021-01-01/versions/latest/tables?format=json
Response
Status: 302 Found
Location: /v1/datasets/uk-tariff-2021-01-01/versions/v2.1.2/tables?format=json

GET data in a version

Entire data of a version of the dataset can be accessed/downloaded using this endpoint

GET /v1/datasets/:dataset/versions/:version/data

Query string parameters

Name Description
format (required) The requested output format. In all cases, this must be json
query-s3-select (optional) A query using the S3 Select query language. If specified, the response is a JSON object with results under the rows key, i.e. {"rows": [...]}, e.g. SELECT * FROM S3Object[*]
download (optional) The presence of this parameter results in a content-disposition header so that browsers attempt to download the data rather than display it inline.

Range requests

If a query-s3-select is not specified, the range HTTP header can be passed to select a byte-range of the dataset. See HTTP Range Requests for more details.

Example without a query

Request
curl -X GET https://data.api.trade.gov.uk/v1/datasets/uk-tariff-2021-01-01/versions/v2.1.0/data?format=json
Response
Status: 200 OK
{
    "capital_cities": [
        {"commodity__code": "0100000000", "commodity__description": "LIVE ANIMALS"},
        {"commodity__code": "0101000000", "commodity__description": "Live horses, asses, mules and hinnies"},
        {"commodity__code": "0101210000", "commodity__description": "Horses"},
    ]
}

Example with a query

Request
curl -X GET https://data.api.trade.gov.uk/v1/datasets/uk-tariff-2021-01-01/versions/v2.1.0/data?format=json&query-s3-select=\
SELECT \
  * \
FROM \
  S3Object[*].uk-tariff-2021-01-01[commodities] AS commodities \
WHERE \
  commodities.commodity__code = '0101210000'
Response
Status: 200 OK
{
    "rows": [
        {"commodity__code": "0101210000", "commodity__description": "Horses"}
    ]
}

Example for latest data

Request

Replacing the version string with the word latest will result in a redirect to the latest version of the dataset.

curl -X GET https://data.api.trade.gov.uk/v1/datasets/uk-tariff-2021-01-01/versions/latest/data?format=json
Response
Status: 302 Found
Location: /v1/datasets/uk-tariff-2021-01-01/versions/v2.1.2/data?format=json

GET data in a table

A version of the dataset can have one or more tables. Each table can be accessed/downloaded using this endpoint

GET /v1/datasets/:dataset/versions/:version/tables/:table/data

Query string parameters

Name Description
format (required) The requested output format. In all cases, this must be csv
download (optional) The presence of this parameter results in a content-disposition header so that browsers attempt to download the data rather than display it inline.

Example

Request
curl -X GET https://data.api.trade.gov.uk/v1/datasets/uk-tariff-2021-01-01/versions/v2.1.0/tables/commodities/data?format=csv
Response
Status: 200 OK
"id","commodity__sid","commodity__code","commodity__suffix","commodity__description","commodity__validity_start","commodity__validity_end","parent__sid","parent__code","parent__suffix"
"1","27623","0100000000","80","LIVE ANIMALS","1971-12-31","#NA","#NA","#NA","#NA"
"2","27624","0101000000","80","Live horses, asses, mules and hinnies","1972-01-01","#NA","27623","0100000000","80"
"3","93797","0101210000","10","Horses","2012-01-01","#NA","27624","0101000000","80"

Example with latest

Replacing the version string with the word latest will result in a redirect to the latest version of the dataset.

Request
curl -X GET https://data.api.trade.gov.uk/v1/datasets/uk-tariff-2021-01-01/versions/latest/tables/commodities/data?format=csv
Response
Status: 302 Found
Location: /v1/datasets/uk-tariff-2021-01-01/versions/v2.1.2/tables/commodities/data?format=csv