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, 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 or A version in the format or A version in the format or The literal |
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. The response is a JSON object with the query results under the Using |
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. |
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 Filtering on rows can then be performed by passing key value pairs |
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. |
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 Filtering on rows can then be performed by passing key value pairs |
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.