HM Revenue and Customs UK Trade Info API

Learn how to use the UK Trade Info API service.

Overview

The UK Trade Info API is based on REST principles with endpoints that return data in JavaScript Object Notification (JSON) format and it uses standard HTTP error response codes. 

Use the API to get access to data about:

  • Overseas Trade Statistics (OTS)
  • Regional Trade Statistics (RTS)
  • imports, exports, traders, commodities, and various other feeds

All endpoints are:

They do not need an Authorisation HTTP header.

Back to contents


Making API requests

To query the HMRC UK Trade Info API, you will need:

  • a way to make HTTP requests, such as curl, Postman or your programming language's library of choice

  • a specific query

With the query to find all traders that exported ‘Live horses (excl. pure-bred for breeding)’ from the ‘CB8’ post code in 2019, you can follow these steps to find your answer.

  1. Create a new GET request.

  2. Point it towards the API’s base endpoint: https://api.uktradeinfo.com

  3. Append this /Commodity to the query: we are searching for ‘Live horses (excl. pure-bred for breeding)’, which is a Harmonised System (HS) level 6 commodity.

  4. Add two query parameters:

    • $filter=Hs6Code eq '010129'
      010129 is the HS6 code for ‘Live horses (excl. pure-bred for breeding)‘. Alternatively, use Hs6Description eq 'Live horses (excl. pure-bred for breeding)'

    • $expand=Exports($filter=MonthId ge 201901 and MonthId le 201912 and startswith(Trader/PostCode, 'CB8'); $expand=Trader)

  5. The full query URL is (follow the link to open the result in a new browser tab): https://api.uktradeinfo.com/Commodity?$filter=Hs6Code eq '010129'&$expand=Exports($filter=MonthId ge 201901 and MonthId le 201912 and startswith(Trader/PostCode, 'CB8'); $expand=Trader)
  6. Make the request.

The API will return a JSON response containing two commodities:

  • one with id 1012910 and an empty list of exports
  • one with id 1012990 and a list of exports

Each export’s trader is also expanded, showing you their company name and address. Only exports for traders with a post code beginning with ‘CB8’ have been returned.

To learn more about using the API, refer to Open Data Protocol(OData) querying tutorials.

Back to contents


Versioning

When an API changes in a way that is backwards-incompatible, we increase the version number of the API. See our reference guide for more on versioning.

Back to contents


Errors

We use standard HTTP status codes to show whether an API request succeeded or not. They are usually in the range:

  • 200 if request has been processed and feedback has been provided

  • 400 to 499 if it failed because of a client error by your application

  • 500 to 599 if it failed because of an error on our server

Back to contents


Content types

Recognised Accept HTTP headers:

  • application/json (default)
  • text/comma separated value (CSV) file  - some limitations

Requesting the CSV content type can also be done with the query parameter: $format=csv added to the URL.

Responses for some complex queries may not be available in CSV format, and will result in a 500 Internal Server Error.

Back to contents


API limits

Response count limit and pagination

There is a 40,000 item limit in the response. These include:

  • imports, exports, trades, traders
  • overseas and regional trade statistics

Queries to these entities will paginate if more items than the limit allows are returned. This is set to make sure that the API is not overloaded by too many large requests - and that it does not timeout.

When the API paginates the results, this new field @odata.nextLink, will be included in the response. This field includes the URL that can be used to fetch the next page of results. All of the required query parameters are pre-populated.

Or, you can do this by setting the query parameter $skip=40000 in the URL (and then 80000, 120000, and so on.). Custom pagination can be achieved for page sizes smaller than the limit. Use a combination of the $skip and $top query parameters for this.

The limit only applies to the final response: aggregations and filtering are still made across the whole dataset before the limit is applied.

Query rate limit

Users of the API are rate-limited to 60 requests per minute. If too many requests are made within that timespan, responses will:

  • fail 
  • state that the limit has been reached

Upon reaching the limit, a user must wait up to a minute before making any more requests.

Back to contents


Endpoints

The following list of endpoints are all OData queryable endpoints that support:

  • $select, $expand, $filter
  • $top, $apply, $count and $format

Use these keywords in any combination of complex queries and aggregation. To learn more about using the API, refer to OData querying tutorials.

Many Microsoft suite tools, such as Microsoft Excel, have built-in OData endpoint connectors for more visual work.

Refer to the API’s Swagger 2 documentation (/swagger/ui/index) for details about each entity’s fields.

The Swagger UI contains examples of:

  • response entities
  • JSON specifications

It can also be used for trying out simple queries, by setting query parameters and making the query. The data queried in this way is live data.

Back to contents

/Commodity

GET /Commodity

Get a list of all Combined Nomenclature (CN) and Harmonised System (HS) commodities. The results can have OData queries applied.

Accept request header: application/json (default) or text/csv.

Back to contents

/Commodity({CommodityId})

GET /Commodity({CommodityId})

Get a single commodity for the given commodity identifier. If no commodity is found, use 404 Not Found.

The commodity identifier is either of these:

  • that commodity's CN8
  • that commodity's HS 2, 4 or 6 code

It will be whichever is most specific, as an integer (with leading zeroes cut off).

Accept request header: application/json (default).

Back to contents

/Country

GET /Country

Get a list of all countries. The results can have OData queries applied.

Accept request header: application/json (default) or text/csv.

Back to contents

/Country({CountryId})

GET /Country({CountryId})

Get a single country for the given country identifier. If no country is found, use 404 Not Found.

The country identifier is an integer.

Accept request header: application/json (default).

Back to contents

/Date

GET /Date

Get a list of all months. The results can have OData queries applied.

Accept request header: application/json (default) or text/csv.

Back to contents

/Date({MonthId})

GET /Date({MonthId})

Get a single month for the given month identifier. If no date is found, use 404 Not Found.

The month identifier is an integer. It is made from appending the two-digit month number (01 for January) to the four-digit year.

Accept request header: application/json (default).

Back to contents

/Export

GET /Export

Get a list of all exports. The results can have OData queries applied.

Paginates at 40,000 results. When paginating, the response contains an @odata.nextLink field with the full URL to the next page of results.

Accept request header: application/json (default) or text/csv.

Back to contents

/Export(CommodityId={CommodityId},MonthId={MonthId},TraderId={TraderId})

GET /Export(CommodityId={CommodityId},MonthId={MonthId},TraderId={TraderId})

Get a single export for the given:

  • commodity identifier
  • month identifier
  • trader identifier

If no export is found, use 404 Not Found. 

Refer to the following endpoint details for information about their respective identifiers:

  • commodity
  • date
  • trader

Accept request header: application/json (default).

Back to contents

/FlowType

GET /FlowType

Get a list of the four flow types. The results can have OData queries applied.

The flow type is used to differentiate between imports and exports from within and outside the EU.

Accept request header: application/json (default) or text/csv.

Back to contents

/FlowType({FlowTypeId})

GET /FlowType({FlowTypeId})

Get a single flow type for the given flow type identifier. If no flow type is found use 404 Not Found.

The flow type identifier is an integer:

  1. EU Imports
  2. EU Exports
  3. Non-EU imports
  4. Non-EU Exports

The flow type identifier is an integer for RTS data:

  1. All Imports
  2. All Exports

Accept request header: application/json (default).

Back to contents

/Import

GET /Import

Get a list of all imports. The results can have OData queries applied.

Paginates at 40,000 results. When paginating, the response contains an @odata.nextLink field with the full URL to the next page of results.

Accept request header: application/json (default) or text/csv.

Back to contents

/Import(CommodityId={CommodityId},MonthId={MonthId},TraderId={TraderId})

GET /Import(CommodityId={CommodityId},MonthId={MonthId},TraderId={TraderId})

Get a single import for the given:

  • commodity identifier
  • month identifier
  • trader identifier

If no import is found, use 404 Not Found.

Refer to these endpoint details for information about their respective identifiers:

  • commodity
  • date
  • trader

Accept request header: application/json (default).

Back to contents

/OTS

GET /OTS

Get a list of all Overseas Trade Statistics (OTS). The results can have OData queries applied.

Paginates at 40,000 results. When paginating, the response contains an @odata.nextLink field with the full URL to the next page of results.

Accept request header: application/json (default) or text/csv.

Back to contents

/OTS(CommodityId={CommodityId},CommoditySitcId={CommoditySitcId},CountryId={CountryId},FlowTypeId={FlowTypeId},MonthId={MonthId},PortId={PortId},SuppressionIndex={SuppressionIndex})

GET /OTS(CommodityId={CommodityId},CommoditySitcId={CommoditySitcId},CountryId={CountryId},FlowTypeId={FlowTypeId},MonthId={MonthId},PortId={PortId},SuppressionIndex={SuppressionIndex})

Get a single Overseas Trade Statistics (OTS) entry for these given identifiers:

  • commodity
  • commodity Standard International Trade Classification (SITC)
  • country 
  • flow type
  • month
  • port
  • suppression index

User 404 Not Found if no OTS entry is found for the given identifiers.

Refer to these endpoint details for information about their respective identifiers:

  • commodity
  • SITC
  • country
  • flow type
  • date
  • port

The suppression index is an integer with one of five values:

  1. Complete suppression, where no information gets published.
  2. Suppression of countries and ports. Only the overall total value (£ sterling) and quantity (kg) get published.
  3. Suppression of countries, ports and total trade quantity. Only the overall total value gets published.
  4. Suppression of quantity for countries and ports. Only the overall total value and quantity get published, but the country and port breakdown is only available for value.
  5. Suppression of quantity for countries, ports and total trade. No information on quantity gets published, but a full breakdown of value is available.

Accept request header: application/json (default).

Back to contents

/Port

GET /Port

Get a list of all ports. The results can have OData queries applied.

Accept request header: application/json (default) or text/csv.

Back to contents

/Port({PortId})

GET /Port({PortId})

Get a single port for the given port identifier. If no port is found, use 404 Not Found.

The port identifier is an integer.

Accept request header: application/json (default).

Back to contents

/Region

GET /Region

Get a list of all regions. The results can have OData queries applied.

Accept request header: application/json (default) or text/csv.

Back to contents

/Region({RegionId})

GET /Region({RegionId})

Get a single region for the given region identifier. If no region is found, use 404 Not Found.

The region identifier is an integer.

Accept request header: application/json (default).

Back to contents

/RTS

GET /RTS

Get a list of all Regional Trade Statistics (RTS). The results can have OData queries applied.

Paginates at 40,000 results. When paginating, the response contains an @odata.nextLink field with the full URL to the next page of results.

Accept request header: application/json (default) or text/csv.

Back to contents

/RTS(CommoditySitc2Id={CommoditySitc2Id},CountryId={CountryId},FlowTypeId={FlowTypeId},GovRegionId={GovRegionId},MonthId={MonthId})

GET /RTS(CommoditySitc2Id={CommoditySitc2Id},CountryId={CountryId},FlowTypeId={FlowTypeId},GovRegionId={GovRegionId},MonthId={MonthId})

Get a single Regional Trade Statistics (RTS) entry for these given identifiers:

  • commodity Standard International Trade Classification (SITC) division level
  • country
  • flow type
  • region
  • month

Use 404 Not Found if no RTS entry is found for the given identifiers.

Refer to these endpoint details for information about their respective identifiers:

  • SITC
  • country
  • flow type
  • region
  • date

Accept request header: application/json (default).

Back to contents

/SITC

GET /SITC

Get a list of all Standard International Trade Classification (SITC) commodities. The results can have OData queries applied.

Accept request header: application/json (default) or text/csv.

Back to contents

/SITC({CommoditySitcId})

GET /SITC({CommoditySitcId})

Get a single Standard International Trade Classification (SITC) commodity for the given SITC identifier. If no SITC commodity is found use 404 Not Found. 

The SITC identifier is that commodity's most specific identifier (2, 3 or 4 digits), as an integer (with leading zeroes cut off).

Accept request header: application/json (default).

Back to contents

/Trade

GET /Trade

Get a list of all trades. The results can have OData queries applied.

Trades are a combination of imports (trade type 1) and exports (trade type 2).

Paginates at 40,000 results. When paginating, the response contains an @odata.nextLink field with the full URL to the next page of results.

Accept request header: application/json (default) or text/csv.

Back to contents

/Trade(CommodityId={CommodityId},MonthId={MonthId},TraderId={TraderId},TradeTypeId={TradeTypeId})

GET /Trade(CommodityId={CommodityId},MonthId={MonthId},TraderId={TraderId},TradeTypeId={TradeTypeId})

Get a single trade for these given identifiers:

  • commodity
  • month
  • trader
  • trade type 

Use 404 Not Found if no trade is found for the given identifiers.

Trades are a combination of imports (trade type 1) and exports (trade type 2).

Refer to these endpoint details for information about their respective identifiers:

  • commodity
  • date
  • trader 

Accept request header: application/json (default).

Back to contents

/Trader

GET /Trader

Get a list of all traders. The results can have OData queries applied.

This paginates at 40,000 results. When paginating, the response contains an @odata.nextLink field with the full URL to the next page of results.

Accept request header: application/json (default) or text/csv.

Back to contents

/Trader({TraderId})

GET /Trader({TraderId})

Get a single trader for the given trader identifier. If no trader is found, use 404 Not Found.

The trader identifier is an integer that uniquely identifies the trader.

Accept request header: application/json (default).

Back to contents

/TradeType

GET /TradeType

Get a list of both trade types. The results can have OData queries applied.

The trade type is used to differentiate between imports (trade type 1) and exports (trade type 2).

Accept request header: application/json (default) or text/csv.

Back to contents

/TradeType({TradeTypeId})

GET /TradeType({TradeTypeId})

Get a single trade type for the given trade type identifier. If no trade type is found use 404 Not Found.

The trade type identifier is an integer: 1 for imports and 2 for exports.

Accept request header: application/json (default).

Back to contents


Sample API queries

Follow the links below to open the result in a new browser tab. These links are representative of common queries received by our Customer Services team.

Display the country and value of EU Imports for the month of November 2022

https://api.uktradeinfo.com/OTS?$filter=Monthid eq 202211 &$select=CountryId, Value

Display the information for countries which had Non-EU OTS Exports between October and November 2022

https://api.uktradeinfo.com/OTS? $expand=Country & $filter=Monthid ge 202210 and MonthId le 202211 &$select=Value

Display all the countries with trade in the Region 017

https://api.uktradeinfo.com/OTS?$apply=filter(Country/RegionId eq '017')/groupby((Country/CountryName))

Display the RTS data for France in the months June 2022 onwards

https://api.uktradeinfo.com/Country?$filter=CountryName%20eq%20%27France%27&$expand=RTS($filter=Monthid%20ge%20202206)

Display the Net Mass from RTS Non-EU Imports for SITCID 1, CountryId 1, Government Region 1 for the month 202203 (Q3 2022)

https://api.uktradeinfo.com/RTS(CommoditySitc2Id=1,CountryId=1,FlowTypeId=3,GovRegionId=1,MonthId=202203)?$select=flowtypeid%2C%20netmass

Display the total RTS value for each country

https://api.uktradeinfo.com/RTS?$apply=groupby((Country/CountryName),%20aggregate(Value%20with%20sum%20as%20TotalValue))

Display the total RTS value for each SITC Description

https://api.uktradeinfo.com/RTS?$apply=groupby((SITC/sITC2dESC),%20aggregate(Value%20with%20sum%20as%20TotalValue))

Back to contents