# UN Comtrade Trade Normalizer (`wakey7dev/comtrade-trade-normalizer`) Actor

Fetch international trade statistics from UN Comtrade and normalize raw codes into clean records with country names, ISO codes and HS commodity descriptions. No API key required.

- **URL**: https://apify.com/wakey7dev/comtrade-trade-normalizer.md
- **Developed by:** [Chris Wakefield](https://apify.com/wakey7dev) (community)
- **Categories:** Business, AI
- **Stats:** 2 total users, 1 monthly users, 100.0% runs succeeded, 0 bookmarks
- **User rating**: No ratings yet

## Pricing

Pay per usage

This Actor is paid per platform usage. The Actor is free to use, and you only pay for the Apify platform usage, which gets cheaper the higher subscription plan you have.

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

## 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

![Chris The Dev](https://raw.githubusercontent.com/chriswakefield87/appstore-screenshot-translator/main/assets/actor-banner.png)

## UN Comtrade Trade Normalizer

Fetch international trade statistics from the **UN Comtrade** database and turn the raw, code-heavy API responses into clean, human-readable records — with country names, ISO codes, HS commodity descriptions, flow direction labels and quantity units. No API key required.

The free Comtrade public preview API returns numeric codes (`reporterCode`, `partnerCode`, `cmdCode`) and leaves description fields empty. This actor resolves every code to a readable label, so you get "United States imports Coffee from Brazil — $1.4bn" instead of `842 → 0901 → 76`.

### What it does

- **Resolves country codes** → full country names + ISO2/ISO3 codes (200+ countries/territories, M49/Comtrade coding)
- **Resolves HS commodity codes** → chapter + commodity descriptions (all 99 HS chapters + 150+ curated 4-digit goods)
- **Accepts keywords** → "coffee", "crude oil", "cars", "wheat", "gold", "semiconductors" and 180+ more aliases
- **Labels trade flows** → Import / Export / Re-import / Re-export
- **Labels quantity units** → kilograms, litres, number of items, etc.
- **Standardizes trade values** → explicit `tradeValueUsd`, `cifValueUsd`, `fobValueUsd` fields

### Input

| Field | Type | Required | Description |
|---|---|---|---|
| `reporter` | string | ✅ | Reporting country (name, ISO code, or M49 code). e.g. "United States", "UK", "842" |
| `partner` | string | — | Trading partner, or "World" for all partners. Default "World" |
| `commodity` | string | ✅ | HS code (e.g. "0901") or keyword (e.g. "coffee") |
| `flow` | select | — | Import / Export / Re-import / Re-export. Default Import |
| `startYear` | integer | — | First year. Default 2022 |
| `endYear` | integer | — | Last year (inclusive). Default 2023 |
| `maxResults` | integer | — | Max records to return. Default 100 |

### Example input

```json
{
  "reporter": "United States",
  "partner": "World",
  "commodity": "coffee",
  "flow": "M",
  "startYear": 2021,
  "endYear": 2023,
  "maxResults": 50
}
```

### Example output

```json
{
  "reporter": "United States",
  "reporterIso3": "USA",
  "partner": "World",
  "flow": "Import",
  "year": 2023,
  "commodityCode": "0901",
  "commodity": "Coffee, whether or not roasted or decaffeinated; coffee husks and skins",
  "chapter": "09",
  "chapterDescription": "Coffee, tea, maté and spices",
  "tradeValueUsd": 8201729476.0,
  "cifValueUsd": 8201729476.0,
  "fobValueUsd": 7998011187.0,
  "quantity": 1389262732.253,
  "quantityUnit": "kilograms",
  "netWeightKg": 1389262732.253
}
```

### Use cases

- **Market research** — track import/export volumes of any commodity by country over time
- **Competitive intelligence** — see who trades what with whom, and how volumes shift
- **Commodity analysis** — year-over-year trade flows for energy, agriculture, metals and electronics
- **Supply chain / logistics** — understand sourcing dependencies and trade corridors
- **Academic & policy research** — normalized, machine-readable trade data for analysis

### Data source

Data is fetched live from the [UN Comtrade](https://comtrade.un.org) public preview API (`comtradeapi.un.org`), the official United Nations international trade statistics database. Data covers annual merchandise trade at the HS commodity level. Attribution: United Nations Comtrade Database.

> **Note:** the free preview API is rate-limited and returns annual data. The actor spaces requests and retries automatically. For the fullest historical coverage, a UN Comtrade subscription key unlocks the complete API.

# Actor input Schema

## `reporter` (type: `string`):

Country that reports the trade (imports/exports). Accepts a name (e.g. 'United States', 'UK', 'China'), ISO code (e.g. 'USA', 'GBR', 'CN') or M49 numeric code (e.g. 842 for USA, 826 for UK, 156 for China).

## `partner` (type: `string`):

Trading partner country, or 'World' for all partners combined. Accepts name, ISO code or numeric code. Default: World.

## `commodity` (type: `string`):

HS commodity code (2-6 digits, e.g. '0901') or a keyword (e.g. 'coffee', 'crude oil', 'cars', 'wheat', 'gold', 'semiconductors').

## `flow` (type: `string`):

Direction of trade flow.

## `startYear` (type: `integer`):

First year of data to fetch.

## `endYear` (type: `integer`):

Last year of data to fetch (inclusive).

## `maxResults` (type: `integer`):

Maximum number of records to return.

## Actor input object example

```json
{
  "reporter": "United States",
  "partner": "World",
  "commodity": "coffee",
  "flow": "M",
  "startYear": 2022,
  "endYear": 2023,
  "maxResults": 100
}
```

# Actor output Schema

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

Full list of normalized trade records as dataset items.

## `summary` (type: `string`):

Human-readable summary table of the trade results.

## `stats` (type: `string`):

Machine-readable run statistics.

# 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 = {
    "reporter": "United States",
    "partner": "World",
    "commodity": "coffee"
};

// Run the Actor and wait for it to finish
const run = await client.actor("wakey7dev/comtrade-trade-normalizer").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 = {
    "reporter": "United States",
    "partner": "World",
    "commodity": "coffee",
}

# Run the Actor and wait for it to finish
run = client.actor("wakey7dev/comtrade-trade-normalizer").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 '{
  "reporter": "United States",
  "partner": "World",
  "commodity": "coffee"
}' |
apify call wakey7dev/comtrade-trade-normalizer --silent --output-dataset

```

## MCP server setup

```json
{
    "mcpServers": {
        "apify": {
            "type": "http",
            "url": "https://mcp.apify.com/?tools=fetch-actor-details,wakey7dev/comtrade-trade-normalizer"
        }
    }
}

```

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/uyfjVGceeM9cfOkfP/builds/ptZAlukRYdzKSk8t4/openapi.json