Windsor Framework Green Lanes Categorisation API
The Green Lanes Categorisation API’s provide access to Category Assessment data for the different Commodities and Subheadings within the Tariff.
These APIs follow the JSON-API format for both request and response, in common with the other OTT APIs documented on this site.
We recommend using a suitable JSON-API client library for your application platform to consume these APIs - possible JSON-API client libraries
Warning
DRAFT: These APIs are currently in development and not yet available.
The APIs are subject to change and this document will be updated as the API development evolves.
An RSS feed is available for notification of changes - see below.
The APIs are subject to change and this document will be updated as the API development evolves.
An RSS feed is available for notification of changes - see below.
Authentication
Access to these APIs will be restricted initially whilst they are in development. Approved partners requiring access should contact the Online Trade Tariff team.
The token should be included with the API request via the standard HTTP Authorization header, eg.
Authorization: Token <SUPPLIED TOKEN>
Base URL
All requests to this API should be prefixed with the following URL:
https://www.trade-tariff.service.gov.uk/xi/api/v2/green_lanes
Authentication
Green Lanes
GET /green_lanes/category_assessments
Returns a list of all category assessments
Returns a list of the all category assessments
To perform this operation, you must be authenticated by means of one of the following methods: http
Parameters
| Parameter | In | Type | Required | Description |
|---|---|---|---|---|
| as_of | query | string(date) | false | Returns the category assessments across all commodities as they existed on the as_of date. Use the format YYYY-MM-DD While as_of is not a required field it is advised to include it with all requests even if requesting data for today to ensure the data returned is correct. |
Example Request
curl -X GET -H "Authorization: Token TOKEN123" https://www.trade-tariff.service.gov.uk/xi/api/v2/green_lanes/category_assessments
curl -X GET -H "Authorization: Token TOKEN123" https://www.trade-tariff.service.gov.uk/xi/api/v2/green_lanes/category_assessments?as_of=2024-01-01
Example Response
{
"data": [
{
"id": "abcd1234",
"type": "category_assessment",
"attributes": {
"category": 1,
"theme": "1.1 Sanctions"
},
"relationships": {
"geographical_area": {
"data": {
"id": "1011",
"type": "geographical_area"
}
},
"excluded_geographical_areas": {
"data": []
},
"exemptions": {
"data": [
{
"id": "D005",
"type": "certificate"
},
{
"id": "C371",
"type": "additional_code"
}
]
}
}
},
{
"id": "abcd1234",
"type": "category_assessment",
"attributes": {
"category": 1,
"theme": "1.1 Sanctions"
},
"relationships": {
"geographical_area": {
"data": {
"id": "1011",
"type": "geographical_area"
}
},
"excluded_geographical_areas": {
"data": []
},
"exemptions": {
"data": []
}
}
}
],
"included": [
{
"id": "1011",
"type": "geographical_area",
"attributes": {
"description": "ERGA OMNES",
"geographical_area_id": "1011"
}
},
{
"id": "D005",
"type": "certificate",
"attributes": {
"certificate_type_code": "D",
"certificate_code": "005",
"description": "Commercial invoice within the framework of undertakings"
}
},
{
"id": "C371",
"type": "additional_code",
"attributes": {
"additional_code_type_id": "C",
"additional_code": "371",
"code": "C371",
"description": "Shanghai Huayi Group Corp. Ltd Double Coin Group (Jiang Su) Tyre Co., Ltd",
"formatted_description": "Shanghai Huayi Group Corp. Ltd Double Coin Group (Jiang Su) Tyre Co., Ltd"
}
}
]
}
Responses
| Status | Meaning | Description | Schema |
|---|---|---|---|
| 200 | OK | An array of CategoryAssessments | CategoryAssessmentListing |
| 401 | Unauthorized | Authorization header is missing or contains an invalid token | None |
| 422 | Unprocessable Entity | Likely incorrectly formatted as_of param |
None |
| 5xx | Server Error | Unexpected error, something went wrong internally | None |
GET /green_lanes/goods_nomenclatures/{id}
Returns Category Assessments for the requested Goods Nomenclature
Returns the requested Goods Nomenclature together with relevant data including a list of the different Category Assessments applicable to this Goods Nomenclature
Each applicable Category Assessment will provide a primary category together with any potential exemptions. If at least one of the exemptions for that Category Assessment are met then that Category Assessment does not apply.
The effective category for the GoodsNomenclature is the most restrictive category from those Category Assessments determined by the API consumers filtering to be applicable (ie not exempted).
If no Category Assessments are applicable, or all if applicable Category Assessments are exempted, then the trade falls under a default category assessment of Category 3.
To perform this operation, you must be authenticated by means of one of the following methods: http
Parameters
| Parameter | In | Type | Required | Description |
|---|---|---|---|---|
| id | path | string | true | Item Id of the Goods Nomenclature you are requesting Category Assessments information for. This is the full 10 digit item id of either a Subheading or Commodity. If you are working with truncated item ids, ie truncated to 6 or 8 significant digits, then pad to 10 with trailing zero’s - so 123456 would submitted as 1234560000. |
| as_of | query | string(date) | false | Returns tariff data as it applies on the as_of date While this is not a required field it is advised to include it with all requests even if requesting data for today to ensure the data returned is correct. As caching is used on the API this will ensure the data returned is as expected. |
| filter[geographical_area_id] | query | string | false | A geographical area code you wish to use to filter the Category Assessment information |
Example Request
curl -X GET -H "Authorization: Token TOKEN123" https://www.trade-tariff.service.gov.uk/xi/api/v2/green_lanes/goods_nomenclatures/0712909000
curl -X GET -H "Authorization: Token TOKEN123" https://www.trade-tariff.service.gov.uk/xi/api/v2/green_lanes/goods_nomenclatures/0712909000?as_of=2024-01-01
curl -X GET -H "Authorization: Token TOKEN123" "https://www.trade-tariff.service.gov.uk/xi/api/v2/green_lanes/goods_nomenclatures/0712909000?filter\[geographical_area_id\]=US"
curl -X GET -H "Authorization: Token TOKEN123" "https://www.trade-tariff.service.gov.uk/xi/api/v2/green_lanes/goods_nomenclatures/0712909000?as_of=2024-01-01&filter\[geographical_area_id\]=US"
Example Response
{
"data": {
"id": "70361",
"type": "goods_nomenclature",
"attributes": {
"goods_nomenclature_item_id": "0702000007",
"description": "Cherry tomatoes",
"number_indents": 1,
"productline_suffix": "80",
"validity_start_date": "1999-01-01T00:00:00.000Z",
"validity_end_date": null
},
"relationships": {
"applicable_category_assessments": {
"data": [
{
"id": "abcd1234",
"type": "category_assessment"
},
{
"id": "c5678def",
"type": "category_assessment"
}
]
}
}
},
"included": [
{
"id": "abcd1234",
"type": "category_assessments",
"attributes": {
"category": 1,
"theme": "1.1 Sanctions"
},
"relationships": {
"geographical_area": {
"data": {
"id": "1011",
"type": "geographical_area"
}
},
"excluded_geographical_areas": {
"data": []
},
"exemptions": {
"data": [
{
"id": "D005",
"type": "certificate"
},
{
"id": "C371",
"type": "additional_code"
}
]
}
}
},
{
"id": "c5678def",
"type": "category_assessment",
"attributes": {
"category": 1,
"theme": "1.1 Sanctions"
},
"relationships": {
"geographical_area": {
"data": {
"id": "1011",
"type": "geographical_area"
}
},
"excluded_geographical_areas": {
"data": []
},
"exemptions": [],
"measures": {
"data": [
{
"id": "20098001",
"type": "measure"
}
]
}
}
},
{
"id": "1011",
"type": "geographical_area",
"attributes": {
"description": "ERGA OMNES",
"geographical_area_id": "1011"
}
},
{
"id": "D005",
"type": "certificate",
"attributes": {
"certificate_type_code": "D",
"certificate_code": "005",
"description": "Commercial invoice within the framework of undertakings"
}
},
{
"id": "C371",
"type": "additional_code",
"attributes": {
"additional_code_type_id": "C",
"additional_code": "371",
"code": "C371",
"description": "Shanghai Huayi Group Corp. Ltd Double Coin Group (Jiang Su) Tyre Co., Ltd",
"formatted_description": "Shanghai Huayi Group Corp. Ltd Double Coin Group (Jiang Su) Tyre Co., Ltd"
}
},
{
"id": "20098001",
"type": "measure",
"attributes": {
"effective_start_date": "2021-01-01T00:00:00.000Z",
"effective_end_date": null
},
"relationships": {
"goods_nomenclature": null,
"data": {
"id": "30256",
"type": "goods_nomenclature"
},
"measure_type": {
"data": {
"id": "410",
"type": "measure_type"
}
},
"footnotes": {
"data": [
{
"id": "CD624",
"type": "footnote"
}
]
}
}
},
{
"id": "30256",
"type": "goods_nomenclature",
"attributes": {
"goods_nomenclature_item_id": "0702000000",
"description": "Tomatoes, fresh or chilled",
"number_indents": 0,
"productline_suffix": "80",
"validity_start_date": "1999-01-01T00:00:00.000Z",
"validity_end_date": null
}
},
{
"id": "110",
"type": "measure_type",
"attributes": {
"description": "Supplementary unit import",
"measure_type_series_description": "Supplementary unit",
"validity_start_date": "1972-01-01T00:00:00.000Z",
"validity_end_date": null,
"measure_type_series_id": "O",
"trade_movement_code": 0
}
},
{
"id": "TN701",
"type": "footnote",
"attributes": {
"code": "TN701",
"description": "According to the Council Regulation (EU) No 692/2014 (OJ L183, p. 9) it shall be prohibited to import into European Union goods originating in Crimea or Sevastopol.\n..."
}
}
]
}
Responses
| Status | Meaning | Description | Schema |
|---|---|---|---|
| 200 | OK | A GoodsNomenclature and a list of Category Assessments | GoodsNomenclature |
| 401 | Unauthorized | Authorization header is missing or contains an invalid token | None |
| 404 | Not Found | Unknown goods nomenclature item id | None |
| 422 | Unprocessable Entity | Likely to be missing or incorrect params | None |
| 5xx | Server Error | Unexpected error, something went wrong internally | None |
Objects
GoodsNomenclature
A goods_nomenclature object
Sample JSON
{
"data": {
"id": "70361",
"type": "goods_nomenclature",
"attributes": {
"goods_nomenclature_item_id": "0702000007",
"description": "Cherry tomatoes",
"number_indents": 1,
"productline_suffix": "80",
"validity_start_date": "1999-01-01T00:00:00.000Z",
"validity_end_date": null
},
"relationships": {
"applicable_category_assessments": {
"data": [
{
"id": "abcd1234",
"type": "category_assessment"
},
{
"id": "c5678def",
"type": "category_assessment"
}
]
}
}
},
"included": [
{
"id": "abcd1234",
"type": "category_assessments",
"attributes": {
"category": 1,
"theme": "1.1 Sanctions"
},
"relationships": {
"geographical_area": {
"data": {
"id": "1011",
"type": "geographical_area"
}
},
"excluded_geographical_areas": {
"data": []
},
"exemptions": {
"data": [
{
"id": "D005",
"type": "certificate"
},
{
"id": "C371",
"type": "additional_code"
}
]
}
}
},
{
"id": "c5678def",
"type": "category_assessment",
"attributes": {
"category": 1,
"theme": "1.1 Sanctions"
},
"relationships": {
"geographical_area": {
"data": {
"id": "1011",
"type": "geographical_area"
}
},
"excluded_geographical_areas": {
"data": []
},
"exemptions": [],
"measures": {
"data": [
{
"id": "20098001",
"type": "measure"
}
]
}
}
},
{
"id": "1011",
"type": "geographical_area",
"attributes": {
"description": "ERGA OMNES",
"geographical_area_id": "1011"
}
},
{
"id": "D005",
"type": "certificate",
"attributes": {
"certificate_type_code": "D",
"certificate_code": "005",
"description": "Commercial invoice within the framework of undertakings"
}
},
{
"id": "C371",
"type": "additional_code",
"attributes": {
"additional_code_type_id": "C",
"additional_code": "371",
"code": "C371",
"description": "Shanghai Huayi Group Corp. Ltd Double Coin Group (Jiang Su) Tyre Co., Ltd",
"formatted_description": "Shanghai Huayi Group Corp. Ltd Double Coin Group (Jiang Su) Tyre Co., Ltd"
}
},
{
"id": "20098001",
"type": "measure",
"attributes": {
"effective_start_date": "2021-01-01T00:00:00.000Z",
"effective_end_date": null
},
"relationships": {
"goods_nomenclature": null,
"data": {
"id": "30256",
"type": "goods_nomenclature"
},
"measure_type": {
"data": {
"id": "410",
"type": "measure_type"
}
},
"footnotes": {
"data": [
{
"id": "CD624",
"type": "footnote"
}
]
}
}
},
{
"id": "30256",
"type": "goods_nomenclature",
"attributes": {
"goods_nomenclature_item_id": "0702000000",
"description": "Tomatoes, fresh or chilled",
"number_indents": 0,
"productline_suffix": "80",
"validity_start_date": "1999-01-01T00:00:00.000Z",
"validity_end_date": null
}
},
{
"id": "110",
"type": "measure_type",
"attributes": {
"description": "Supplementary unit import",
"measure_type_series_description": "Supplementary unit",
"validity_start_date": "1972-01-01T00:00:00.000Z",
"validity_end_date": null,
"measure_type_series_id": "O",
"trade_movement_code": 0
}
},
{
"id": "TN701",
"type": "footnote",
"attributes": {
"code": "TN701",
"description": "According to the Council Regulation (EU) No 692/2014 (OJ L183, p. 9) it shall be prohibited to import into European Union goods originating in Crimea or Sevastopol.\n..."
}
}
]
}
Fields
| Name | Type | Required | Description |
|---|---|---|---|
| id | string | true | The unique id for this revision of this Goods Nomenclature |
| goods_nomenclature_item_id | string | true | The goods_nomenclature_item_id of this Goods Nomenclature |
| description | string | true | The description of the goods nomenclature |
| number_indents | integer | true | The indentation of the goods nomenclature within the Tariff hierarchy |
| productline_suffix | string | true | The productline_suffix of the goods nomenclature |
| validity_start_date | string(date-time) | true | The date this Goods Nomenclature is valid from |
| validity_end_date | string(date-time) | true | The date this Goods Nomenclature is valid until, null if valid indefinitely |
| applicable_category_assessments | [CategoryAssessment] | false | A list of applicable Category Assessments for this Goods Nomenclature |
CategoryAssessment
A CategoryAssessment for the requested GoodsNomenclature
Sample JSON
{
"data": {
"id": "abcd1234",
"type": "category_assessment",
"attributes": {
"category": 1,
"theme": "1.1 Sanctions"
},
"relationships": {
"geographical_area": {
"data": {
"id": "1011",
"type": "geographical_area"
}
},
"excluded_geographical_areas": {
"data": []
},
"exemptions": {
"data": [
{
"id": "D005",
"type": "certificate"
},
{
"id": "C371",
"type": "additional_code"
}
]
}
}
},
"included": [
{
"id": "1011",
"type": "geographical_area",
"attributes": {
"description": "ERGA OMNES",
"geographical_area_id": "1011"
}
},
{
"id": "D005",
"type": "certificate",
"attributes": {
"certificate_type_code": "D",
"certificate_code": "005",
"description": "Commercial invoice within the framework of undertakings"
}
},
{
"id": "C371",
"type": "additional_code",
"attributes": {
"additional_code_type_id": "C",
"additional_code": "371",
"code": "C371",
"description": "Shanghai Huayi Group Corp. Ltd Double Coin Group (Jiang Su) Tyre Co., Ltd",
"formatted_description": "Shanghai Huayi Group Corp. Ltd Double Coin Group (Jiang Su) Tyre Co., Ltd"
}
}
]
}
Fields
| Name | Type | Required | Description |
|---|---|---|---|
| id | string | true | The unique identifier for this category assessement |
| category | integer | true | The category applicable unless exemption criteria are met |
| theme | string | true | The Green Lanes theme relevant for this Category Assessment |
| geographical_area | GeographicalArea | true | The geographical area this Category Assessment applies to |
| excluded_geographical_areas | [GeographicalArea] | false | The geographical areas excluded from this Category Assessment |
| exemptions | [Unknown] | false | The Certificates or Additional Codes which when supplied exempt a Goods Nomenclature from this Category Assessment NB - Polymorphic array of Certificate and Additional Code objects |
| measures | [Measure] | false | A list of Measures resulting in this CategoryAssessment |
GeographicalArea
A GeographicalArea object
Sample JSON
{
"data": {
"id": "1011",
"type": "geographical_area",
"attributes": {
"description": "ERGA OMNES",
"geographical_area_id": "1011"
}
}
}
Fields
| Name | Type | Required | Description |
|---|---|---|---|
| id | string | true | The id of this geographical area |
| description | string | true | The description of the geographical area |
| geographical_area_id | string | true | The geographical_area_id of the geographical area |
Certificate
A Certificate object
Sample JSON
{
"data": {
"id": "D005",
"type": "certificate",
"attributes": {
"certificate_type_code": "D",
"certificate_code": "005",
"description": "Commercial invoice within the framework of undertakings"
}
}
}
Fields
| Name | Type | Required | Description |
|---|---|---|---|
| id | string | true | The unique identifier for this description |
| certificate_type_code | string | true | The certificate_type_code for the certificate |
| certificate_code | string | true | The certificate_code for the certificate |
| description | string | true | The description for the certificate |
AdditionalCode
An AdditionalCode object
Sample JSON
{
"data": {
"id": "C371",
"type": "additional_code",
"attributes": {
"additional_code_type_id": "C",
"additional_code": "371",
"code": "C371",
"description": "Shanghai Huayi Group Corp. Ltd Double Coin Group (Jiang Su) Tyre Co., Ltd",
"formatted_description": "Shanghai Huayi Group Corp. Ltd Double Coin Group (Jiang Su) Tyre Co., Ltd"
}
}
}
Fields
| Name | Type | Required | Description |
|---|---|---|---|
| id | string | true | The unique identifier for this additional_code object |
| additional_code_type_id | string | true | The additional_code_type_id for the additional_code |
| additional_code | string | true | The additional_code for the additional_code |
| code | string | true | The code for the additional_code. Equal to additional_code_type_id + additional_code
|
| description | string | true | The description for the additional_code |
| formatted_description | string | true | The formatted_description for the additional_code |
Measure
A Measure object which generates this Category Assessment.
Sample JSON
{
"data": {
"id": "20098001",
"type": "measure",
"attributes": {
"effective_start_date": "2021-01-01T00:00:00.000Z",
"effective_end_date": null
},
"relationships": {
"goods_nomenclature": {
"data": {
"id": "30256",
"type": "goods_nomenclature"
}
},
"measure_type": {
"data": {
"id": "410",
"type": "measure_type"
}
},
"footnotes": {
"data": [
{
"id": "CD624",
"type": "footnote"
}
]
}
}
}
}
Fields
| Name | Type | Required | Description |
|---|---|---|---|
| id | string | true | The unique identifier for this measure |
| effective_start_date | string(date-time) | true | The effective start date of the measure. |
| effective_end_date | string(date-time) | true | The effective end date of the measure. |
| measure_type | MeasureType | false | The measure type associated with this measure |
| goods_nomenclature | ReferencedGoodsNomenclature | false | The goods nomenclature this measure is directly against |
| footnotes | [Footnote] | false | The footnotes for this measure |
MeasureType
A referenced MeasureType object
Sample JSON
{
"data": {
"id": "110",
"type": "measure_type",
"attributes": {
"description": "Supplementary unit import",
"measure_type_series_description": "Supplementary unit",
"validity_start_date": "1972-01-01T00:00:00.000Z",
"validity_end_date": null,
"measure_type_series_id": "O",
"trade_movement_code": 0
}
}
}
Fields
| Name | Type | Required | Description |
|---|---|---|---|
| id | string | false | Unique identifier for this measure |
| description | string | false | The description for the measure type |
| measure_type_series_description | string | false | The description of the measure type series |
| validity_start_date | string(date-time) | false | The validity start date of the measure type |
| validity_end_date | string(date-time) | false | The validity end date of the measure type |
| measure_type_series_id | string(byte) | false | A single char representing measure type series. |
| trade_movement_code | integer | false | The code of trade movement. |
Footnote
A referenced Footnote object
Sample JSON
{
"data": {
"id": "TN701",
"type": "footnote",
"attributes": {
"code": "TN701",
"description": "According to the Council Regulation (EU) No 692/2014 (OJ L183, p. 9) it shall be prohibited to import into European Union goods originating in Crimea or Sevastopol.\n..."
}
}
}
Fields
| Name | Type | Required | Description |
|---|---|---|---|
| id | string | false | Unique identifier for the footnote |
| code | string | false | The code for the footnote |
| description | string | false | The description for the footnote |
ReferencedGoodsNomenclature
A referenced GoodsNomenclature which a measure is against
Sample JSON
{
"data": {
"id": "70361",
"type": "goods_nomenclature",
"attributes": {
"goods_nomenclature_item_id": "0702000000",
"description": "Tomatoes, fresh or chilled",
"number_indents": 0,
"productline_suffix": "80",
"validity_start_date": "1999-01-01T00:00:00.000Z",
"validity_end_date": null
}
}
}
Fields
| Name | Type | Required | Description |
|---|---|---|---|
| id | string | true | The unique id for this revision of this Goods Nomenclature |
| goods_nomenclature_item_id | string | true | The goods_nomenclature_item_id of this Goods Nomenclature |
| description | string | true | The description of the goods nomenclature |
| number_indents | integer | true | The indentation of the goods nomenclature within the Tariff hierarchy |
| productline_suffix | string | true | The productline_suffix of the goods nomenclature |
| validity_start_date | string(date-time) | true | The date this Goods Nomenclature is valid from |
| validity_end_date | string(date-time) | true | The date this Goods Nomenclature is valid until, null if valid indefinitely |
CategoryAssessmentListing
Listing of all category assessments
Sample JSON
{
"data": [
{
"id": "abcd1234",
"type": "category_assessment",
"attributes": {
"category": 1,
"theme": "1.1 Sanctions"
},
"relationships": {
"geographical_area": {
"data": {
"id": "1011",
"type": "geographical_area"
}
},
"excluded_geographical_areas": {
"data": []
},
"exemptions": {
"data": [
{
"id": "D005",
"type": "certificate"
},
{
"id": "C371",
"type": "additional_code"
}
]
}
}
},
{
"id": "abcd1234",
"type": "category_assessment",
"attributes": {
"category": 1,
"theme": "1.1 Sanctions"
},
"relationships": {
"geographical_area": {
"data": {
"id": "1011",
"type": "geographical_area"
}
},
"excluded_geographical_areas": {
"data": []
},
"exemptions": {
"data": []
}
}
}
],
"included": [
{
"id": "1011",
"type": "geographical_area",
"attributes": {
"description": "ERGA OMNES",
"geographical_area_id": "1011"
}
},
{
"id": "D005",
"type": "certificate",
"attributes": {
"certificate_type_code": "D",
"certificate_code": "005",
"description": "Commercial invoice within the framework of undertakings"
}
},
{
"id": "C371",
"type": "additional_code",
"attributes": {
"additional_code_type_id": "C",
"additional_code": "371",
"code": "C371",
"description": "Shanghai Huayi Group Corp. Ltd Double Coin Group (Jiang Su) Tyre Co., Ltd",
"formatted_description": "Shanghai Huayi Group Corp. Ltd Double Coin Group (Jiang Su) Tyre Co., Ltd"
}
}
]
}
Fields
| Name | Type | Required | Description |
|---|---|---|---|
| id | string | true | The unique identifier for this category assessement |
| category | integer | true | The category applicable unless exemption criteria are met Category 1 = Prohibited Category 2 = Controlled Category 3 = Exempted |
| geographical_area | GeographicalArea | true | The geographical area this Category Assessment applies to |
| excluded_geographical_areas | [GeographicalArea] | false | The geographical areas excluded from this Category Assessment |
| exemptions | [Unknown] | false | The Certificates or Additional Codes which when supplied exempt a Goods Nomenclature from this Category Assessment NB - Polymorphic array of Certificate and Additional Code objects |