UN Comtrade Trade Data Scraper

Extract import/export trade rows from the public UN Comtrade API by country, partner, HS commodity code, period, and flow. Use this actor to turn UN Comtrade JSON into a clean Apify dataset that is ready for spreadsheets, BI tools, procurement research, compliance monitoring, and market sizing.

What does UN Comtrade Trade Data Scraper do?

UN Comtrade Trade Data Scraper collects structured international trade records from the public UN Comtrade API.

It helps you answer questions such as:

• 🌍 What did the United States import from the world in 2023?
• 🚢 Which HS commodity groups are growing for a reporter country?
• 📈 How do imports and exports compare across periods?
• 🧾 What CIF, FOB, quantity, and weight values are reported for a trade lane?
• 🔎 Which partner countries are relevant for a sourcing or market entry analysis?

The actor accepts UN reporter codes, partner codes, periods, HS commodity codes, and flow codes, then saves normalized rows to the default dataset.

Who is it for?

This actor is built for analysts who need repeatable trade-data collection without writing API scripts.

• 📊 Trade analysts monitoring import/export flows
• 🛒 Procurement and sourcing teams comparing supplier countries
• 🏭 Manufacturers tracking commodity and component markets
• 🧭 Market researchers sizing cross-border demand
• 🛡️ Compliance and intelligence teams checking country exposure
• 💼 Consultants preparing trade lane or tariff impact reports
• 🧪 Data teams feeding warehouses, dashboards, or notebooks

Why use this actor?

UN Comtrade is a valuable source, but raw API work can be repetitive. You need to know the endpoint, parameter names, country codes, HS codes, and response shape. This actor packages that into a reusable Apify workflow.

Benefits:

• ✅ Public HTTP/API source, no browser required
• ✅ Batches multiple countries, periods, commodities, and flows
• ✅ Normalizes values into typed dataset columns
• ✅ Includes source URL and timestamp for auditability
• ✅ Supports cheap smoke tests and larger analysis runs
• ✅ Ready for Apify integrations, webhooks, API clients, and MCP

What data can it extract?

The actor saves one dataset row per UN Comtrade trade record.

Field	Description
period	Requested period such as 2023
reporterCode	UN numeric reporter code
reporterISO	Reporter ISO code when provided
reporterName	Reporter country or area name
partnerCode	UN numeric partner code
partnerISO	Partner ISO code when provided
partnerName	Partner country, area, or World
flowCode	Flow code such as M or X
flowName	Flow label such as Import or Export
commodityCode	HS commodity code
commodityName	Commodity description
quantity	Reported quantity
quantityUnit	Quantity unit abbreviation
netWeightKg	Net weight in kilograms when present
grossWeightKg	Gross weight in kilograms when present
cifValueUsd	CIF value in USD when present
fobValueUsd	FOB value in USD when present
tradeValueUsd	Primary trade value in USD
sourceUrl	API URL used for the record
scrapedAt	ISO timestamp for the actor run

How much does it cost to extract UN Comtrade trade data?

This actor uses pay-per-event pricing.

• A small start fee is charged once per run.
• A per-row event is charged for each trade row saved.
• You control cost with maxRows.
• Use small inputs first, then scale to more reporters, partners, periods, and HS codes.

The actor is designed as an HTTP/API scraper, so it does not use browsers or paid proxies by default.

How to use it

1. Open the actor on Apify.
2. Enter one or more reporter country/area codes.
3. Enter partner codes. Use 0 for World.
4. Enter one or more periods.
5. Enter HS commodity codes such as TOTAL, 01, 02, or 8703.
6. Choose flow codes such as M for imports and X for exports.
7. Set maxRows to cap output volume.
8. Run the actor.
9. Download the dataset as JSON, CSV, Excel, XML, or RSS.

Input reference

Reporter country/area codes

Use UN Comtrade numeric reporter codes.

Examples:

• 842 — USA
• 156 — China
• 276 — Germany
• 392 — Japan
• 826 — United Kingdom

Partner country/area codes

Use UN Comtrade numeric partner codes. The default 0 means World.

Periods

For annual frequency, use years such as 2023 or 2022.

For monthly frequency, use periods supported by the UN Comtrade API.

HS commodity codes

Use TOTAL for all commodities or HS chapters/headings such as:

• 01 — live animals
• 27 — mineral fuels
• 84 — machinery
• 85 — electrical machinery
• 8703 — motor cars

Flow codes

Common flow codes:

• M — imports
• X — exports

Advanced users can add other public API flow codes if supported by UN Comtrade.

Limits and delays

maxRows stops output after a specific number of rows. requestDelayMillis adds a delay between batched API calls to be polite to the public source.

Example input

{
  "reporterCodes": ["842", "156"],
  "partnerCodes": ["0"],
  "periods": ["2023", "2022"],
  "commodityCodes": ["TOTAL", "01", "02", "03", "04", "05", "06", "07", "08", "09", "10", "11", "12", "13", "14", "15", "16", "17", "18", "19", "20", "21", "22", "23", "24"],
  "flowCodes": ["M", "X"],
  "frequency": "A",
  "classification": "HS",
  "tradeType": "C",
  "includeDescriptions": true,
  "maxRows": 100,
  "requestDelayMillis": 250
}

Example output

{
  "period": "2023",
  "reporterName": "USA",
  "partnerName": "World",
  "flowName": "Import",
  "commodityCode": "TOTAL",
  "commodityName": "All Commodities",
  "tradeValueUsd": 3168471121076,
  "cifValueUsd": 3168471121076,
  "fobValueUsd": 3080052528515,
  "quantity": 0,
  "quantityUnit": "N/A",
  "sourceUrl": "https://comtradeapi.un.org/public/v1/preview/C/A/HS?...",
  "scrapedAt": "2026-06-30T00:00:00.000Z"
}

Tips for better trade-data runs

• Start with partnerCodes: ["0"] for World totals.
• Use TOTAL before drilling down into HS chapters.
• Keep maxRows low while testing a new combination.
• Add more periods only after you confirm your reporter and commodity codes return data.
• Use imports and exports together for quick trade-balance checks.
• If a run returns no rows, verify the reporter, partner, period, HS code, and flow combination in UN Comtrade.

Common workflows

Market sizing

Collect imports by HS code for a target reporter country and compare yearly values.

Sourcing analysis

Run a reporter country against multiple partner countries to identify supply concentration.

Export opportunity research

Compare export flows for competitor countries and commodity chapters.

Compliance monitoring

Track flows for sensitive commodities and countries over time.

Dashboard refreshes

Schedule the actor and send results to a warehouse or BI tool.

Integrations

Apify datasets connect to many downstream workflows.

• Google Sheets for analyst review
• BigQuery or Snowflake for warehousing
• Make or Zapier for alerts
• Webhooks for run-complete automation
• Python notebooks for modelling
• BI tools for trend dashboards

API usage: Node.js

import { ApifyClient } from 'apify-client';

const client = new ApifyClient({ token: process.env.APIFY_TOKEN });
const run = await client.actor('automation-lab/un-comtrade-trade-data-scraper').call({
  reporterCodes: ['842'],
  partnerCodes: ['0'],
  periods: ['2023'],
  commodityCodes: ['TOTAL', '84', '85'],
  flowCodes: ['M', 'X'],
  maxRows: 20,
});

const { items } = await client.dataset(run.defaultDatasetId).listItems();
console.log(items);

API usage: Python

from apify_client import ApifyClient

client = ApifyClient('YOUR_APIFY_TOKEN')
run = client.actor('automation-lab/un-comtrade-trade-data-scraper').call(run_input={
    'reporterCodes': ['842'],
    'partnerCodes': ['0'],
    'periods': ['2023'],
    'commodityCodes': ['TOTAL', '84', '85'],
    'flowCodes': ['M', 'X'],
    'maxRows': 20,
})

items = client.dataset(run['defaultDatasetId']).list_items().items
print(items)

API usage: cURL

curl -X POST "https://api.apify.com/v2/acts/automation-lab~un-comtrade-trade-data-scraper/runs?token=$APIFY_TOKEN" \
  -H 'Content-Type: application/json' \
  -d '{
    "reporterCodes": ["842"],
    "partnerCodes": ["0"],
    "periods": ["2023"],
    "commodityCodes": ["TOTAL", "84", "85"],
    "flowCodes": ["M", "X"],
    "maxRows": 20
  }'

MCP: use with Claude and other AI tools

You can connect this actor through the Apify MCP server and ask AI tools to run trade-data tasks.

MCP URL:

https://mcp.apify.com/?tools=automation-lab/un-comtrade-trade-data-scraper

Claude Code setup:

$claude mcp add apify-un-comtrade https://mcp.apify.com/?tools=automation-lab/un-comtrade-trade-data-scraper

Claude Desktop JSON config:

{
  "mcpServers": {
    "apify-un-comtrade": {
      "url": "https://mcp.apify.com/?tools=automation-lab/un-comtrade-trade-data-scraper"
    }
  }
}

Example prompts:

• "Run UN Comtrade Trade Data Scraper for USA imports from World in 2023 for HS 84 and 85."
• "Compare China exports for TOTAL commodities in 2022 and 2023."
• "Fetch the first 100 UN Comtrade rows for USA and Germany imports by HS chapters."

Scheduling

Use Apify schedules to refresh trade data weekly, monthly, or quarterly. Scheduled runs are useful for dashboards and recurring market reports.

Webhooks

Use Apify webhooks to trigger a downstream workflow after each run. For example, send the dataset to a warehouse, Slack alert, or custom API endpoint.

Data quality notes

UN Comtrade data availability depends on reporting countries, periods, commodities, and publication schedules. Some combinations return no rows. Some weight or quantity fields may be null or N/A depending on the reported data.

Error handling

The actor retries transient API failures and rate-limit responses. If the public API returns an error field, the actor logs it. Enable failOnApiError if you want the run to stop on API error messages.

Performance

The actor batches multiple values per request, which reduces API calls. It also supports a small delay between requests to avoid hammering the public service.

Legality

This actor uses a public UN Comtrade API endpoint and stores factual trade records. You are responsible for using the data in compliance with UN Comtrade terms, Apify terms, and laws that apply to your project.

FAQ

Why did I get zero rows?

The selected reporter, partner, period, commodity, and flow combination may not exist in the public dataset. Try partnerCodes: ["0"], commodityCodes: ["TOTAL"], and one recent annual period first.

What does partner code 0 mean?

Partner code 0 means World totals in UN Comtrade responses.

Can I use monthly data?

Yes. Set frequency to M and provide periods supported by the UN Comtrade monthly API.

Does this actor use proxies?

No. It calls a public HTTP API directly.

Can I request thousands of rows?

Yes, but start smaller. Increase maxRows after verifying your query produces the expected rows.

Related scrapers

Explore other Automation Labs actors for market research and public data workflows:

• https://apify.com/automation-lab/google-search-results-scraper
• https://apify.com/automation-lab/website-contact-finder
• https://apify.com/automation-lab/rss-feed-scraper

Changelog

• Initial version: public UN Comtrade API extraction for reporter, partner, period, HS commodity, and flow filters.