HM Revenue and Customs UK Trade Info API
Learn how to use the UK Trade Info API service.
Contents
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:
- open access
- can be queried
They do not need an Authorisation HTTP header.
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.
-
Create a new GET request.
-
Point it towards the API’s base endpoint:
https://api.uktradeinfo.com
-
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. -
Add two query parameters:
-
$filter=Hs6Code eq '010129'
010129 is the HS6 code for ‘Live horses (excl. pure-bred for breeding)‘. Alternatively, useHs6Description 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)
-
- 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)
-
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.
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.
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
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.
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.
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.
/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
.
/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).
/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
.
/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).
/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
.
/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).
/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
.
/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).
/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
.
/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:
- EU Imports
- EU Exports
- Non-EU imports
- Non-EU Exports
The flow type identifier is an integer for RTS data:
- All Imports
- All Exports
Accept request header: application/json
(default).
/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
.
/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).
/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
.
/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:
- Complete suppression, where no information gets published.
- Suppression of countries and ports. Only the overall total value (£ sterling) and quantity (kg) get published.
- Suppression of countries, ports and total trade quantity. Only the overall total value gets published.
- 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.
- 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).
/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
.
/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).
/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
.
/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).
/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
.
/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).
/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
.
/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).
/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
.
/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).
/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
.
/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).
/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
.
/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).
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