HMRC UK Trade Info API technical documentation

Find technical documentation for the UK Trade Info API service.

Overview

The HMRC UK Trade Info API provides access to data for Overseas Trade Statistics (OTS), Regional Trade Statistics (RTS), imports, exports, traders, commodities, and various other feeds.

All endpoints are open access, queryable and do not require an Authorization HTTP header.

Getting started

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 goal

With the goal 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 /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 2 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 2 commodities: one with id 1012910 and an empty list of exports, and the other 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 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/csv (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

Entities that increase in number over time (Imports, Exports, Trades, OTS, RTS, Traders) have a 30,000 (thirty thousand) item limit in the response. Queries to these entities will paginate if more items than the limit allows would be returned. This is a hard limit that 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, a new field will be included in the response: @odata.nextLink. 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). Alternatively, you can do this by setting the query parameter $skip=30000 in the URL (and then 60000, 90000, and so on.). Custom pagination can be achieved for page sizes smaller than the limit by using a combination of the $skip and $top query parameters.

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 and 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. These keywords, when used in combination with one another, will enable you to perform complex queries and aggregations. 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, as well as their 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 CN (Common Nomenclature) and HS (Harmonised System) 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, or 404 Not Found if no commodity is found for the given commodity identifier.

The commodity identifier is that commodity's CN8 (Common Nomenclature) or HS (Harmonised System) 2, 4 or 6 code, 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, or 404 Not Found if no country is found for the given country identifier.

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, or 404 Not Found if no date is found for the given month identifier.

The month identifier is an integer 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 30,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 and trader identifier, or 404 Not Found if no export is found for the given identifiers.

Refer to the commodity, date and trader endpoint details for information about their respective identifiers.

Accept request header: application/json (default).

/Import

GET /Import

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

Paginates at 30,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 and trader identifier, or 404 Not Found if no import is found for the given identifiers.

Refer to the commodity, date and trader endpoint details for information about their respective identifiers.

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 30,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 the given commodity identifier, commodity Standard International Trade Classification (SITC) identifier, country identifier, flow type identifier, month identifier, port identifier and suppression index, or 404 Not Found if no OTS entry is found for the given identifiers.

Refer to the commodity, SITC, country, date and port endpoint details for information about their respective identifiers.

The flow type identifier is an integer with one of four values:

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

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

  1. Complete suppression, where no information is published.
  2. Suppression of countries and ports, where only the overall total value (£ sterling) and quantity (kg) are published.
  3. Suppression of countries, ports and total trade quantity, where only the overall total value is published.
  4. Suppression of quantity for countries and ports, where the overall total value and quantity are published, but where a country and port breakdown is only available for value.
  5. Suppression of quantity for countries, ports and total trade, where no information on quantity is 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, or 404 Not Found if no port is found for the given identifier.

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, or 404 Not Found if no region is found for the given identifier.

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 30,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 the given commodity Standard International Trade Classification (SITC) division level identifier, country identifier, flow type identifier, region identifier and month identifier, or 404 Not Found if no RTS entry is found for the given identifiers.

Refer to the SITC, country, region and date endpoint details for information about their respective identifiers.

Refer to the OTS endpoint details for information about the flow type identifier.

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, or 404 Not Found if no SITC commodity is found for the given identifier.

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 30,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 the given commodity identifier, month identifier, trader identifier and trade type identifier, or 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 the commodity, date and trader endpoint details for information about their respective identifiers.

Accept request header: application/json (default).

/Trader

GET /Trader

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

Paginates at 30,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, or 404 Not Found if no trader is found for the given identifier.

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, or 404 Not Found if no trade type is found for the given identifier.

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

Accept request header: application/json (default).