Skip to main content

Data API

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

  • Datasets are versioned
  • Each dataset version is immutable
  • Each dataset version has one or more tables
  • Each dataset version has zero or more reports - a report contains filtered or aggregated table data
  • Metadata for each dataset version is available as HTML or CSVW (CSV on the Web)
  • Data can be filtered or aggregated using the S3 Select query language
  • Data is supplied as SQLite, JSON, CSV, or ODS (OpenDocument Spreadsheet).

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

Getting started

Any tool that can make HTTPS requests can access the Data API. Examples are curl, Postman, or the web browser you're currently using.

For example https://data.api.trade.gov.uk/v1/datasets?format=json will return a list of datasets.

Base URL

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

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

Versioning

Datasets are versioned according to a subset of the Semver 2.0 specification. Each version is of the form X.Y.Z, where X is the major version, Y is the minor version, and Z is the patch version. Each release of a dataset increments the version according to the following rules.

  • Patch: incremented when data is added or changed, but the structure of the data is the same.
  • Minor: incremented when new fields or tables are added to the data, but existing ones are unchanged.
  • Major: incremented when existing fields are removed or change type.

Reports

Datasets can contain reports. Reports are similar to tables, except that the data in reports is generated from the tables in the dataset. Reports are available to satisfy common use cases for filtered or aggregated views of the data in a dataset.

If a dataset is available as SQLite, reports are generated using SQL in the _reports table in the SQLite file.

Common parameters

Several URL parameters are applicable to multiple API endpoints.

Name Description
dataset_id A human-readable identifier of a dataset, e.g. uk-tariff-2021-01-01
version_id

A version identifier in the format vX.Y.Z, where X.Y.Z is the Semver 2.0 version of the dataset, e.g. v2.1.0

or

A version in the format vX.Y. In this case, a HTTP 302 redirect is returned to the URL requested, but with version_id equal to the latest version of the dataset with major and minor components matching vX.Y

or

A version in the format vX. In this case, a HTTP 302 redirect is returned to the URL requested, but with version_id equal to the latest version of the dataset with major component matching vX

or

The literal latest. In this case, a HTTP 302 redirect is returned to the URL requested, but with version_id equal to the latest version of the dataset
table_id A human-readable identifier of a table, e.g. commodities
report_id A human-readable identifier of a report, e.g. quotas-including-current-volumes

API Endpoints

GET list of datasets

The list of all datasets available in the Data API can be accessed using this endpoint.

GET /v1/datasets

Query string parameters

Name Required Description
format Yes The requested output format. In all cases, this must be json

Example

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

GET list of versions of a dataset

The list of versions of each dataset can be accessed using this endpoint.

GET /v1/datasets/{dataset_id}/versions

Query string parameters

Name Required Description
format Yes The requested output format. In all cases, this must be json

Example

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

GET list of tables in a version

The list of tables of each dataset version can be accessed using this endpoint.

GET /v1/datasets/{dataset_id}/versions/{version_id}/tables

Query string parameters

Name Required Description
format Yes The requested output format. In all cases, this must be json

Example

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

GET list of reports in a version

The list of reports of each dataset version can be accessed using this endpoint.

GET /v1/datasets/{dataset_id}/versions/{version_id}/reports

Query string parameters

Name Required Description
format Yes The requested output format. In all cases, this must be json

Example

Request
curl --get https://data.api.trade.gov.uk/v1/datasets/uk-trade-quotas/versions/v1.0.0/reports \
    --data-urlencode "format=json"
Response
Status: 200 OK
{
    "reports": [
        {"id": "quotas-including-current-volumes"}
    ]
}

GET metadata of a version

The metadata of a dataset version can be accessed using this endpoint.

GET /v1/datasets/{dataset_id}/versions/{version_id}/metadata

Query string parameters

Name Required Description
format Yes The requested output format. This must be csvw or html
download No The presence of this parameter results in a content-disposition header so that browsers attempt to download the metadata rather than display it inline

Example requesting CSVW

Request
curl --get https://data.api.trade.gov.uk/v1/datasets/uk-tariff-2021-01-01/versions/v2.1.0/metadata \
    --data-urlencode "format=csvw"
Response (excerpt)
Status: 200 OK
{
  "@context": [
    "http://www.w3.org/ns/csvw",
    {"dit": "http://data.api.trade.gov.uk/"}
  ],
  "dc:title": "Tariffs to trade with the UK from 1 January 2021",
  ...
  "tables": [{
    "id": "commodities",
    ...
    "tableSchema": {
      "columns": [{
        "name": "id",
        ...
      }, ...]
    }
  }, ...]
}

GET data in a version

All of the data of a dataset version can be accessed using this endpoint

GET /v1/datasets/{dataset_id}/versions/{version_id}/data

Query string parameters

Name Required Description
format Yes The requested output format. This must be sqlite, json, or ods
query-s3-select No

A query using the S3 Select query language, e.g. SELECT * FROM S3Object[*]

The response is a JSON object with the query results under the rows key, i.e. {"rows": [...]}

Using query-s3-select requires that the format parameter be json.
download No 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 --get https://data.api.trade.gov.uk/v1/datasets/uk-tariff-2021-01-01/versions/v2.1.0/data \
    --data-urlencode "format=json"
Response (excerpt)
Status: 200 OK
{
    "commodities": [
        {"id": "1", "commodity__code": "0100000000", ...
        ...
    ],
    ...
}

Example with a query

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

GET data in a table

The data of single table in a dataset version can be accessed using this endpoint.

GET /v1/datasets/{dataset_id}/versions/{version_id}/tables/{table_id}/data

Query string parameters

Name Required Description
format Yes The requested output format. This must be csv or ods
query-s3-select No

A query using the S3 Select query language, e.g. SELECT * FROM S3Object
query-simple No

Enables a "simple" query mode to specify columns to retrieve, and filter rows using exact matching.

In simple mode, the value of each _columns parameter is a single column to include in the output. This parameter can be passed multiple times to include multiple columns.

Filtering on rows can then be performed by passing key value pairs column=value. The output includes only those rows where column column equals value.
download No 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 query-s3-select and query-simple are not specified, the range HTTP header can be passed to select a byte-range of the table. See HTTP Range Requests for more details.

Example without a query

Request
curl --get https://data.api.trade.gov.uk/v1/datasets/uk-tariff-2021-01-01/versions/v2.1.0/tables/commodities/data \
    --data-urlencode "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 an S3 Select query

Request
curl --get https://data.api.trade.gov.uk/v1/datasets/uk-tariff-2021-01-01/versions/v2.1.0/tables/commodities/data \
    --data-urlencode "format=csv" \
    --data-urlencode "query-s3-select=
        SELECT
            c.commodity__code, c.commodity__suffix, c.commodity__description
        FROM
            S3Object c
        WHERE
            c.commodity__code = '0101210000'
        LIMIT
            1
    "
Response
Status: 200 OK
0101210000,10,Horses

Example with a simple query

Request
curl --get https://data.api.trade.gov.uk/v1/datasets/uk-tariff-2021-01-01/versions/v2.1.0/tables/commodities/data \
    --data-urlencode "format=csv" \
    --data-urlencode "query-simple" \
    --data-urlencode "commodity__code=0101210000" \
    --data-urlencode "_columns=commodity__code" \
    --data-urlencode "_columns=commodity__suffix" \
    --data-urlencode "_columns=commodity__description"
Response
Status: 200 OK
commodity__code,commodity__suffix,commodity__description
0101210000,10,Horses
0101210000,80,Pure-bred breeding animals

GET data in a report

The data of a single report in a dataset version can be accessed using this endpoint.

GET /v1/datasets/{dataset_id}/versions/{version_id}/reports/{report_id}/data

Query string parameters

Name Required Description
format Yes The requested output format. This must be csv or ods
query-s3-select No

A query using the S3 Select query language, e.g. SELECT * FROM S3Object
query-simple No

Enables a "simple" query mode to specify columns to retrieve, and filter rows using exact matching.

In simple mode, the value of each _columns parameter is a single column to include in the output. This parameter can be passed multiple times to include multiple columns.

Filtering on rows can then be performed by passing key value pairs column=value. The output includes only those rows where column column equals value.
download No 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 query-s3-select and query-simple are not specified, the range HTTP header can be passed to select a byte-range of the report. See HTTP Range Requests for more details.

Example without a query

Request
curl --get https://data.api.trade.gov.uk/v1/datasets/uk-trade-quotas/versions/v1.0.0/reports/quotas-including-current-volumes/data \
    --data-urlencode "format=csv"
Response (excerpt)
Status: 200 OK
"quota_definition__sid","quota__order_number","quota__geographical_areas","quota__headings","quota__commodities","quota__measurement_unit","quota__monetary_unit","quota_definition__description","quota_definition__validity_start_date","quota_definition__validity_end_date","quota_definition__suspension_periods","quota_definition__blocking_periods","quota_definition__status","quota_definition__last_allocation_date","quota_definition__initial_volume","quota_definition__balance","quota_definition__fill_rate"
20815,50006,"ERGA OMNES","0302 – Fish, fresh or chilled, excluding fish fillets and other fish meat of heading|0304|0303 – Fish, frozen, excluding fish fillets and other fish meat of heading 0304|0304 – Fish fillets and other fish meat (whether or not minced), fresh, chilled or frozen","0302410000|0303510000|0304595000|0304599010|0304992300","Kilogram (kg)","#NA","#NA","2021-01-01","2021-02-14","#NA","#NA","Closed","2021-01-28",2022900,2022900.0,0.0
20814,50006,"ERGA OMNES","0302 – Fish, fresh or chilled, excluding fish fillets and other fish meat of heading|0304|0303 – Fish, frozen, excluding fish fillets and other fish meat of heading 0304|0304 – Fish fillets and other fish meat (whether or not minced), fresh, chilled or frozen","0302410000|0303510000|0304595000|0304599010|0304992300","Kilogram (kg)","#NA","#NA","2021-06-16","2022-02-14","#NA","#NA","Open","#NA",2112000,2112000.0,0.0

Example with an S3 Select query

Request
curl --get https://data.api.trade.gov.uk/v1/datasets/uk-trade-quotas/versions/v1.0.0/reports/quotas-including-current-volumes/data \
    --data-urlencode "format=csv" \
    --data-urlencode "query-s3-select=
        SELECT
            q.quota__order_number, q.quota_definition__validity_start_date, q.quota_definition__status, q.quota_definition__initial_volume, q.quota_definition__balance
        FROM
            S3Object q
        WHERE
            q.quota__commodities LIKE '%0203195900%'
    "
Response
Status: 200 OK
50123,2021-01-01,Exhausted,2000,0.0
50123,2021-07-01,Open,1349000,1349000.0
51921,2021-01-01,Open,1632000,1632000.0
51944,2021-01-01,Critical,167000,147000.0
57220,2021-01-01,Open,494000,494000.0
59282,2021-01-01,Open,4838000,4838000.0

Example with a simple query

Request
curl --get https://data.api.trade.gov.uk/v1/datasets/uk-trade-quotas/versions/v1.0.0/reports/quotas-including-current-volumes/data \
    --data-urlencode "format=csv" \
    --data-urlencode "query-simple" \
    --data-urlencode "quota__order_number=50123" \
    --data-urlencode "_columns=quota__order_number" \
    --data-urlencode "_columns=quota_definition__validity_start_date" \
    --data-urlencode "_columns=quota_definition__status" \
    --data-urlencode "_columns=quota_definition__initial_volume" \
    --data-urlencode "_columns=quota_definition__balance"
Response
Status: 200 OK
quota__order_number,quota_definition__validity_start_date,quota_definition__status,quota_definition__initial_volume,quota_definition__balance
50123,2021-01-01,Exhausted,2000,0.0
50123,2021-07-01,Open,1349000,1349000.0

Support

For help with the Data API please create an issue on its GitHub issues page.

Security

To report a security vulnerability please contact us at pentest@trade.gov.uk.

Accessibility

Please find the accessibility statement.