internal.staging.public-data-api.uktrade.digital Open in urlscan Pro
13.42.220.125  Malicious Activity! Public Scan

Form analysis
0 forms found in the DOM

Text Content

Skip to main content
Department for Business and Trade Data API

Table of contents
 * Data API
   * Getting started
   * Base URL
   * Versioning
   * Reports
   * Common parameters
   * API Endpoints
     * GET list of datasets
     * GET list of versions of a dataset
     * GET list of tables in a version
     * GET list of reports in a version
     * GET metadata of a version
     * GET data in a version
     * GET data in a table
     * GET data in a report
   * Support
   * Security
   * Accessibility


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://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 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://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 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://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 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://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.

All content is available under the Open Government Licence v3.0, except where
otherwise stated
© Crown copyright