Getting Started

This guide introduces a number of key concepts in GOV.UK Trade Tariff API through the usage of examples. It utilises curl for interfacing with the API on the command line and is chosen due to the wide availability of curl, however you may prefer the structured output of using HTTPie or piping the curl responses through jq.

Accessing Content

GOV.UK Trade Tariff API is used to access content that is hosted on www.gov.uk/trade-tariff. For a given commodity, for example Pure-bred breeding animals, we can look this up through this API:

curl https://www.trade-tariff.service.gov.uk/api/v2/commodities/0101210000

If you would like to view the equivalent data for the EU Tariff as applies to certain trades in Northern Ireland (known as the XI Tariff), then access via this API:

curl https://www.trade-tariff.service.gov.uk/xi/api/v2/commodities/0101210000

This will return a commodity object. Within this object are fields that describe the commodity itself, it import and export measures, footnotes, metadata and associations and other content.

Harmonized System

The Harmonized Commodity Description and Coding System, also known as the Harmonized System (HS) of tariff nomenclature is an internationally standardized system of names and numbers to classify traded products.

The HS is organized logically by economic activity or component material. The HS is organized into 21 sections, which are subdivided into 99 chapters. The 99 chapters are further subdivided into approximately 5,000 headings and subheadings.

Many of the objects returned from this API include a goods_nomenclature_item_id field, which is an implementation of the Combined Nomenclature, a system of classifying goods under the HS.

{
  ...
  "goods_nomenclature_item_id": "0101210000",
  ...
}

Every commodity (e.g., heading and sub-heading) has a goods_nomenclature_item_id and this value is used to identify any commodity in the Tariff.

Making use of content

Ruby on Rails

It can be simple to make use of API in your application. The example below utilises Ruby on Rails with Rest Client.

require "rest-client"

commodity = Rails.cache.fetch("/api/v1/commodities/0101210000", expires_in: 1.day) do
  response = RestClient.get("https://www.trade-tariff.service.gov.uk/api/v1/commodities/0101210000", { content_type: "json" })
  JSON.parse(response.body).dig("details", "body")
end

content = "<h1>GOV.UK Tariff Information</h1><div>#{commodity}</div>"

In this example we utilise the Rails cache so that we can infrequently can minimise the number of times we call the API. The Trade Tariff is updated daily so a cache of 1 day is recommended.

We then use the API to access the content for Pure-bred breeding animals. In the response we access the body field from within the details object. We store this to a variable commodity.

Finally we embed this in our own Ruby on Rails app and are ready to output to users.

node.js with Axios

The example below uses node.js and the popular Axios module, a Promise-based HTTP client for node.js and the browser. Here, we retrieve a commodity and print its formatted_description to the console.

const axios = require('axios');

axios.get('https://www.trade-tariff.service.gov.uk/api/v1/commodities/0101210000')
     .then(response => {
       console.log(response.data.formatted_description);
      })
     .catch(error => {
       console.log(error);
     });

Note the use of .then() to handle the Promise, and errors are handled by .catch(). Axios handles converting the JSON response to a javascript object.