Data API

The Department for Business and 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, Apache Parquet, 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://internal.staging.public-data-api.uktrade.digital/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://internal.staging.public-data-api.uktrade.digital

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://internal.staging.public-data-api.uktrade.digital/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://internal.staging.public-data-api.uktrade.digital/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://internal.staging.public-data-api.uktrade.digital/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://internal.staging.public-data-api.uktrade.digital/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://internal.staging.public-data-api.uktrade.digital/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

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.

query-s3-select

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://internal.staging.public-data-api.uktrade.digital/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`, `ods`, or `parquet`
`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://internal.staging.public-data-api.uktrade.digital/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://internal.staging.public-data-api.uktrade.digital/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://internal.staging.public-data-api.uktrade.digital/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`, `ods`, or `parquet`
`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://internal.staging.public-data-api.uktrade.digital/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://internal.staging.public-data-api.uktrade.digital/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://internal.staging.public-data-api.uktrade.digital/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 None.

Accessibility

Please find the accessibility statement.