# UK Tariff Commodity Records — HS Codes & Taxonomy (`nexgensignal/uk-tariff-commodity-records`) Actor

Keyless, pay-per-record UK tariff commodity taxonomy — one row per commodity code with description, validity dates and parent-code hierarchy. Open Government Licence v3.0; no person data.

- **URL**: https://apify.com/nexgensignal/uk-tariff-commodity-records.md
- **Developed by:** [NexGen Signal](https://apify.com/nexgensignal) (community)
- **Categories:** Business, News, Other
- **Stats:** 2 total users, 1 monthly users, 100.0% runs succeeded, 0 bookmarks
- **User rating**: No ratings yet

## Pricing

from $33.50 / 1,000 commodity records

This Actor is paid per event. You are not charged for the Apify platform usage, but only a fixed price for specific events.
Since this Actor supports Apify Store discounts, the price gets lower the higher subscription plan you have.

Learn more: https://docs.apify.com/actors/running/actors-in-store.md#pay-per-event

## What's an Apify Actor?

Actors are web data automations that power AI and operations. They run on the Apify platform to scrape websites, process data, connect APIs, and automate workflows.
In Batch mode, an Actor accepts a well-defined JSON input, performs an action which can take anything from a few seconds to a few hours,
and optionally produces a well-defined JSON output, datasets with results, or files in key-value store.
In Standby mode, an Actor provides a web server which can be used as a website, API, or an MCP server.
Actors are written with capital "A".

## How to integrate an Actor?

If asked about integration, you help developers integrate Actors into their projects.
You adapt to their stack and deliver integrations that are safe, well-documented, and production-ready.
The best way to integrate Actors is as follows.

- **AI agents and MCP clients** — the [Apify MCP server](https://docs.apify.com/integrations/mcp.md) at `https://mcp.apify.com` (remote, streamable HTTP, OAuth on first use).
- **Agentic workflows and local Actor development** — [Agent Skills](https://apify.com/.well-known/agent-skills/index.json) with the [Apify CLI](https://docs.apify.com/cli/docs.md): `npm install -g apify-cli`, then `apify login`.
- **JavaScript/TypeScript projects** — the official [JS/TS client](https://docs.apify.com/api/client/js/docs.md): `npm install apify-client`.
- **Python projects** — the official [Python client](https://docs.apify.com/api/client/python/docs.md): `pip install apify-client`.
- **Any other language** — the [REST API](https://docs.apify.com/api/v2.md).

For usage examples, see the [API](#api) section below.

For more details, see Apify documentation as [Markdown index](https://docs.apify.com/llms.txt) and [Markdown full-text](https://docs.apify.com/llms-full.txt).

# README

## UK Tariff Commodity Records — HS Codes & Taxonomy

**Keyless. Pay per record. The full UK commodity-code taxonomy, ready to join.**

This actor turns the **UK Integrated Online Tariff** into clean, per-commodity records — the complete classification tree of goods for UK imports and exports. Each run reads the official keyless tariff API and delivers one row per commodity code: the 10-digit code and its product-line suffix, the description, the validity dates, and the parent code that places it in the hierarchy. Commodity-taxonomy grain, structured for engineering use, under the Open Government Licence, with no personal data of any kind.

### What this is, in one paragraph

Every good crossing the UK border is classified by a commodity code — a hierarchy that starts at two-digit chapters (live animals, machinery, textiles) and descends to ten-digit lines. This actor reads the official tariff's commodities table and flattens each node into a single analysis-ready record: code, suffix, description, when it became valid and when (if ever) it ended, and the parent code above it. It is the reference taxonomy that classification, customs, and trade-analytics systems build on. Values are exactly as published. You are billed only for records actually delivered.

### Who buys this and for what job

- **Customs, freight, and trade-compliance software** that needs the current UK commodity-code tree as clean rows to power classification and validation.
- **Cross-border e-commerce and ERP integrations** mapping products to HS/commodity codes for duty and documentation.
- **Trade-data and analytics teams** joining shipment or product data to the official code descriptions and hierarchy.
- **Data engineers** who want the taxonomy without paging the tariff API and reshaping it by hand.

### Open Government Licence — free commercial reuse

One licence rider travels on every record. UK Integrated Online Tariff data is published under the **Open Government Licence v3.0 (OGL v3.0)** — free to copy, publish, distribute, and adapt, **including commercially**, provided the required attribution is given: "Contains public sector information licensed under the Open Government Licence v3.0." This is reference taxonomy, not tariff/duty-rate advice or a customs classification ruling — verify the live tariff before any customs decision.

### Commodity grain — no person data

This actor works at commodity-taxonomy grain: codes, descriptions, and the hierarchy between them. There are no natural-person fields in this data, and this actor emits none.

### Pricing

| Event | Free plan | Bronze | Silver | Gold / Platinum / Diamond |
|-------|-----------|--------|--------|---------------------------|
| `commodity_record` | $0.05 | $0.045 | $0.04 | $0.0335 |

Delivered before charged. Blocked runs and empty results cost nothing.

### Input

| Field | Type | Default | Description |
|-------|------|---------|-------------|
| `codePrefix` | string | — | Optional. Keep only commodity codes starting with these digits (e.g. 01, 8471). |
| `descriptionContains` | string | — | Optional. Keep only commodities whose description contains this text. |
| `maxRecords` | integer | 500 | Ceiling on records delivered and billed. |

### Output

One JSON object per commodity node. Real example (values as published):

```json
{
  "record_id": "93797",
  "commodity_sid": "93797",
  "commodity_code": "0101210000",
  "commodity_suffix": "10",
  "description": "Horses",
  "validity_start": "2012-01-01",
  "validity_end": null,
  "parent_sid": "27624",
  "parent_code": "0101000000",
  "parent_suffix": "80",
  "source": "UK Integrated Online Tariff",
  "source_url": "https://www.trade-tariff.service.gov.uk/",
  "licence": "UK Integrated Online Tariff ... Open Government Licence v3.0 ...",
  "attribution": "Contains public sector information licensed under the Open Government Licence v3.0. ...",
  "disclaimer": "Commodity-code taxonomy records ... reference taxonomy, not tariff/duty-rate advice ...",
  "observed_at": "2026-08-21T00:00:00Z"
}
```

An unbilled `RUN_RECEIPT` records the robots check, the filters, rows seen and delivered, and whether charged equals delivered.

### Field reference

Each record is one commodity node. Identity: `record_id` / `commodity_sid`, `commodity_code`, and `commodity_suffix`. Content: `description`. Change metadata (carried verbatim): `validity_start` and `validity_end`. Hierarchy: `parent_sid`, `parent_code`, and `parent_suffix` — join `parent_code` to `commodity_code` to walk up the tree. Provenance: `source`, `source_url`, `licence`, `attribution`, `disclaimer`, and `observed_at`.

### How a run works

A run first re-reads the source host's robots posture from your runtime — the tariff API host serves no robots file, a no-policy posture — and stops at the door if that ever changes. It then streams the official commodities table from the tariff's latest version, applies your optional `codePrefix` and `descriptionContains` filters, and flattens each matching node to one record — carrying the validity dates verbatim as change metadata — delivered **before** it is charged, so a blocked or empty run costs you nothing. The actor stops at your `maxRecords` ceiling and records `charge_equals_delivered` in the receipt.

### Coverage and scope

The tariff's commodities table holds on the order of **70,000+ nodes** spanning the full classification tree — chapters, headings, subheadings, and ten-digit lines. Because each record carries its `parent_code`, the hierarchy reconstructs by a simple self-join, and the validity dates let you distinguish current lines from historical ones. Pass a `codePrefix` to pull a single chapter or heading (say, `8471` for automatic data-processing machines), or a `descriptionContains` to find every line mentioning a term.

### Working with the hierarchy

The commodity tree is self-describing: every node carries the `parent_code` of the node above it, so the full ancestry of any ten-digit line reconstructs with a simple recursive self-join on `commodity_code` = `parent_code`. That lets you roll a specific product line up to its heading and chapter for aggregation, or expand a chapter down to all of its lines for coverage. The `commodity_suffix` distinguishes the declarable product line (suffix `80`) from intermediate grouping nodes (suffix `10`), so a classification system can pick exactly the level it needs. And because `validity_start` and `validity_end` travel on every record verbatim, two pulls taken weeks apart can be diffed to see which codes were introduced, retired, or re-parented between tariff versions — the change signal that keeps a downstream classification table current without re-ingesting the whole tree each time.

### Cost guidance

One `commodity_record` per delivered node: cost = nodes delivered × your plan's per-record price. Scope with `codePrefix` to keep runs bounded — a single chapter is typically a few hundred to a few thousand lines, so a targeted pull of one product area costs a few dollars rather than the whole tree. Pull the full taxonomy once to seed a table, then take small `codePrefix` pulls to keep the areas you care about fresh. 1,000 nodes is **$50** (Free) / **$33.50** (Gold), and the whole ~70,000-node tree is well under **$2,400** at Gold if you ever need the complete snapshot in one run.

### Honest limitations

- **Reference, not advice.** This is the classification taxonomy, not duty rates, measures, or a customs classification ruling. Consult the live tariff for those.
- **As published.** Codes, descriptions, hierarchy, and validity dates are exactly as the tariff distributes them; this actor reformats, it does not interpret.
- **Latest version.** Records come from the tariff's latest published version at run time.
- **No person data** of any kind.

### Differentiation

This is a **net-new** category for the NexGenData fleet — no existing fleet actor covers the UK commodity-code taxonomy. It is distinct from the fleet's trade and customs cells for other countries (which carry trade flows, not the UK classification tree) and from the fleet's UK company and regulatory cells. Its specific job is the **UK tariff commodity taxonomy** — the reference code tree, with hierarchy and validity — that classification and customs systems join against.

### The NexGen Signal family

Part of the NexGen Signal family of pay-per-record data products:

- [US Treasury Fiscal Records — Rates & Debt](https://apify.com/nexgensignal/treasury-fiscal-records)
- [ECB Bank Lending & Deposit Rate Records — Euro Area MIR](https://apify.com/nexgensignal/ecb-bank-interest-rate-records)
- [National Macro Indicator Records — World Bank](https://apify.com/nexgensignal/national-macro-indicator-records)
- [EU Regulatory Change Records — CELLAR](https://apify.com/nexgensignal/eu-regulatory-change-records)
- [UK Contract Opportunity Records](https://apify.com/nexgensignal/uk-contract-opportunity-records)

*Source: UK Integrated Online Tariff (data.api.trade.gov.uk). Contains public sector information licensed under the Open Government Licence v3.0 — free to reuse, including commercially, with attribution. Reference taxonomy only, not tariff/duty-rate advice or a customs classification ruling. No person data.*

# Actor input Schema

## `codePrefix` (type: `string`):

Optional. Keep only commodity codes starting with these digits (e.g. 01 for live animals, 8471 for computers).

## `descriptionContains` (type: `string`):

Optional. Keep only commodities whose description contains this text (case-insensitive).

## `maxRecords` (type: `integer`):

Maximum records delivered and billed.

## Actor input object example

```json
{
  "maxRecords": 500
}
```

# Actor output Schema

## `results` (type: `string`):

Delivered commodity records.

# API

You can run this Actor programmatically using our API. Below are code examples in JavaScript, Python, and CLI, as well as the OpenAPI specification and MCP server setup.

## JavaScript example

```javascript
import { ApifyClient } from 'apify-client';

// Initialize the ApifyClient with your Apify API token
// Replace the '<YOUR_API_TOKEN>' with your token
const client = new ApifyClient({
    token: '<YOUR_API_TOKEN>',
});

// Prepare Actor input
const input = {
    "maxRecords": 500
};

// Run the Actor and wait for it to finish
const run = await client.actor("nexgensignal/uk-tariff-commodity-records").call(input);

// Fetch and print Actor results from the run's dataset (if any)
console.log('Results from dataset');
console.log(`💾 Check your data here: https://console.apify.com/storage/datasets/${run.defaultDatasetId}`);
const { items } = await client.dataset(run.defaultDatasetId).listItems();
items.forEach((item) => {
    console.dir(item);
});

// 📚 Want to learn more 📖? Go to → https://docs.apify.com/api/client/js/docs

```

## Python example

```python
from apify_client import ApifyClient

# Initialize the ApifyClient with your Apify API token
# Replace '<YOUR_API_TOKEN>' with your token.
client = ApifyClient("<YOUR_API_TOKEN>")

# Prepare the Actor input
run_input = { "maxRecords": 500 }

# Run the Actor and wait for it to finish
run = client.actor("nexgensignal/uk-tariff-commodity-records").call(run_input=run_input)

# Fetch and print Actor results from the run's dataset (if there are any)
print(f"💾 Check your data here: https://console.apify.com/storage/datasets/{run.default_dataset_id}")
for item in client.dataset(run.default_dataset_id).iterate_items():
    print(item)

# 📚 Want to learn more 📖? Go to → https://docs.apify.com/api/client/python/docs/quick-start

```

## CLI example

```bash
echo '{
  "maxRecords": 500
}' |
apify call nexgensignal/uk-tariff-commodity-records --silent --output-dataset

```

## MCP server setup

```json
{
    "mcpServers": {
        "apify": {
            "type": "http",
            "url": "https://mcp.apify.com/?tools=fetch-actor-details,nexgensignal/uk-tariff-commodity-records"
        }
    }
}

```

The hosted server signs you in with OAuth on first connect, so no API token belongs in this config. Clients without OAuth support can send an `Authorization: Bearer <APIFY_API_TOKEN>` header instead, using a token from API & Integrations in Apify Console (https://console.apify.com/settings/integrations).

## OpenAPI specification

Download the OpenAPI definition: https://api.apify.com/v2/actors/K0Qp9vCO9O5YkLgQC/builds/ddRsymXGrPR7jhYFd/openapi.json