# UN Comtrade Scraper (`crawlerbros/un-comtrade-scraper`) Actor Scrape UN Comtrade international trade statistics - bilateral trade flows, commodity data by HS/BEC/SITC codes, import/export values, weights, and quantities for any country pair. - **URL**: https://apify.com/crawlerbros/un-comtrade-scraper.md - **Developed by:** [Crawler Bros](https://apify.com/crawlerbros) (community) - **Categories:** Automation, Developer tools, Integrations - **Stats:** 2 total users, 1 monthly users, 100.0% runs succeeded, 4 bookmarks - **User rating**: 5.00 out of 5 stars ## Pricing from $3.00 / 1,000 results This Actor is paid per event and usage. You are charged both the fixed price for specific events and for Apify platform usage. Since this Actor supports Apify Store discounts, the price gets lower the higher subscription plan you have. Learn more: https://docs.apify.com/platform/actors/running/actors-in-store#pay-per-event ## What's an Apify Actor? Actors are a software tools running on the Apify platform, for all kinds of web data extraction and automation use cases. 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. In JavaScript/TypeScript projects, use official [JavaScript/TypeScript client](https://docs.apify.com/api/client/js.md): ```bash npm install apify-client ``` In Python projects, use official [Python client library](https://docs.apify.com/api/client/python.md): ```bash pip install apify-client ``` In shell scripts, use [Apify CLI](https://docs.apify.com/cli/docs.md): ````bash # MacOS / Linux curl -fsSL https://apify.com/install-cli.sh | bash # Windows irm https://apify.com/install-cli.ps1 | iex ```bash In AI frameworks, you might use the [Apify MCP server](https://docs.apify.com/platform/integrations/mcp.md). If your project is in a different language, use 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 ## UN Comtrade Scraper Extract international trade statistics from the **United Nations Comtrade** database — the world's most comprehensive repository of bilateral trade flow data. Covers 200+ countries, 5,000+ HS commodity codes, and annual/monthly series going back decades. No API key is required. This actor uses the public preview endpoint. --- ### What Can It Do? - **Fetch commodity trade flows** — imports and exports between any country pair for any HS/BEC/SITC commodity code - **Get all-commodity totals** — aggregate trade value for a country's full trade - **List reporter countries** — get all valid country codes for use in queries - **Annual & monthly data** — choose your time granularity - **Commodity classification** — HS (Harmonized System), BEC, or SITC --- ### Input | Field | Type | Description | Example | |-------|------|-------------|---------| | `mode` | select | `getCommodityTrade` or `listReporters` | `getCommodityTrade` | | `typeCode` | select | `C` (Commodity) or `S` (Service) | `C` | | `freqCode` | select | `A` (Annual) or `M` (Monthly) | `A` | | `clCode` | select | `HS`, `BEC`, or `SITC` | `HS` | | `reporterCode` | string | Numeric country code (842=USA, 36=AUS, 826=UK) | `842` | | `partnerCode` | string | Partner country code; `0` = World | `0` | | `cmdCode` | string | HS commodity code or `TOTAL` | `8471` | | `period` | string | Year (`2022`) or year-month (`202201`) | `2022` | | `maxItems` | integer | Records cap (1–500) | `100` | #### Common Country Codes | Code | Country | |------|---------| | 842 | United States | | 36 | Australia | | 826 | United Kingdom | | 156 | China | | 276 | Germany | | 392 | Japan | | 381 | Italy | | 251 | France | | 124 | Canada | | 356 | India | #### Common HS Commodity Codes | Code | Description | |------|-------------| | TOTAL | All commodities | | 8471 | Automatic data processing machines (computers) | | 2709 | Crude petroleum oils | | 8703 | Passenger motor vehicles | | 8517 | Telephones and smartphones | | 8542 | Integrated circuits | | 1001 | Wheat | | 2601 | Iron ores | | 3004 | Medicaments | | 7108 | Gold | --- ### Output Each record contains: | Field | Type | Description | |-------|------|-------------| | `period` | string | Year (e.g. "2022") or year-month | | `reporterCode` | integer | Numeric country code of reporter | | `reporterISO` | string | ISO-3 code (e.g. "USA") | | `reporterDesc` | string | Country name | | `flowCode` | string | M=Import, X=Export, DX=Re-export | | `flowDesc` | string | Human-readable flow description | | `partnerCode` | integer | Numeric partner country code | | `partnerISO` | string | Partner ISO-3 code | | `partnerDesc` | string | Partner country name | | `cmdCode` | string | HS commodity code | | `cmdDesc` | string | Commodity description | | `tradeValue` | float | Trade value in USD | | `netWgt` | float | Net weight in kg | | `grossWgt` | float | Gross weight in kg | | `qty` | float | Quantity | | `qtyUnitCode` | integer | Quantity unit code | | `qtyUnitAbbr` | string | Quantity unit abbreviation | | `isReporter` | boolean | Whether this is a reporter country | | `sourceUrl` | string | Source URL | | `recordType` | string | "trade" or "reporter" | | `scrapedAt` | string | ISO timestamp of scrape | --- ### Example Use Cases #### 1. US Computer Imports from All Partners (2022) ```json { "mode": "getCommodityTrade", "reporterCode": "842", "partnerCode": "0", "cmdCode": "8471", "period": "2022", "maxItems": 100 } ```` #### 2. Total Trade for Germany (Annual 2023) ```json { "mode": "getCommodityTrade", "reporterCode": "276", "cmdCode": "TOTAL", "period": "2023", "freqCode": "A" } ``` #### 3. Monthly Oil Trade (January 2023) ```json { "mode": "getCommodityTrade", "reporterCode": "842", "cmdCode": "2709", "period": "202301", "freqCode": "M" } ``` #### 4. List All Reporter Countries ```json { "mode": "listReporters", "maxItems": 500 } ``` *** ### Frequently Asked Questions **Do I need an API key?** No. This actor uses the UN Comtrade public preview endpoint which is free and requires no registration. **How many records can I get?** The public API returns up to 500 records per request. Set `maxItems` accordingly. **What are reporter vs. partner countries?** The reporter is the country submitting the trade data (the one whose customs records are used). The partner is the country they traded with. **What does partnerCode=0 mean?** Code 0 means "World" — all trade partners aggregated together. **What if data comes back empty?** The public preview API has limited coverage. Some country/commodity/period combinations may not be in the preview dataset. Try a more common country like USA (842) or a recent year. **What is the HS classification?** The Harmonized System (HS) is an international standard for classifying traded goods. 6-digit codes identify specific products; 2-digit "chapters" group related goods. **Can I get service trade data?** Yes, set `typeCode` to `S`. Service data is less granular than commodity data. *** ### Data Source Data comes from the [UN Comtrade database](https://comtradeapi.un.org/), maintained by the United Nations Statistics Division. It is the largest repository of international merchandise trade data. # Actor input Schema ## `mode` (type: `string`): What to fetch: trade data for a commodity, or a list of valid reporter countries. ## `typeCode` (type: `string`): Commodity (goods) or Service trade. ## `freqCode` (type: `string`): Annual or Monthly data. ## `clCode` (type: `string`): Classification system for the commodity code. The public preview API only supports HS (Harmonized System). BEC and SITC require a paid API subscription. ## `reporterCode` (type: `string`): Numeric ISO country code of the reporting country. Examples: 842=USA, 36=Australia, 826=UK, 156=China, 276=Germany, 392=Japan. ## `partnerCode` (type: `string`): Numeric ISO code for the trade partner. Use 0 for World (all partners aggregated). Examples: 0=World, 156=China, 842=USA, 276=Germany. ## `cmdCode` (type: `string`): HS commodity code to filter by. Examples: 8471=computers, 2709=crude oil, 8703=passenger cars, TOTAL=all commodities, AG2=all 2-digit chapters. ## `period` (type: `string`): Year for annual data (e.g. 2022) or year-month for monthly data (e.g. 202201 for January 2022). ## `maxItems` (type: `integer`): Maximum number of records to return. Public API limit is 500 per request. ## Actor input object example ```json { "mode": "getCommodityTrade", "typeCode": "C", "freqCode": "A", "clCode": "HS", "reporterCode": "842", "partnerCode": "0", "cmdCode": "8471", "period": "2022", "maxItems": 100 } ``` # Actor output Schema ## `tradeRecords` (type: `string`): Dataset containing all scraped trade flow or reporter 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 '' with your token const client = new ApifyClient({ token: '', }); // Prepare Actor input const input = { "mode": "getCommodityTrade", "typeCode": "C", "freqCode": "A", "clCode": "HS", "reporterCode": "842", "partnerCode": "0", "cmdCode": "8471", "period": "2022", "maxItems": 100 }; // Run the Actor and wait for it to finish const run = await client.actor("crawlerbros/un-comtrade-scraper").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 '' with your token. client = ApifyClient("") # Prepare the Actor input run_input = { "mode": "getCommodityTrade", "typeCode": "C", "freqCode": "A", "clCode": "HS", "reporterCode": "842", "partnerCode": "0", "cmdCode": "8471", "period": "2022", "maxItems": 100, } # Run the Actor and wait for it to finish run = client.actor("crawlerbros/un-comtrade-scraper").call(run_input=run_input) # Fetch and print Actor results from the run's dataset (if there are any) print("💾 Check your data here: https://console.apify.com/storage/datasets/" + run["defaultDatasetId"]) for item in client.dataset(run["defaultDatasetId"]).iterate_items(): print(item) # 📚 Want to learn more 📖? Go to → https://docs.apify.com/api/client/python/docs/quick-start ``` ## CLI example ```bash echo '{ "mode": "getCommodityTrade", "typeCode": "C", "freqCode": "A", "clCode": "HS", "reporterCode": "842", "partnerCode": "0", "cmdCode": "8471", "period": "2022", "maxItems": 100 }' | apify call crawlerbros/un-comtrade-scraper --silent --output-dataset ``` ## MCP server setup ```json { "mcpServers": { "apify": { "command": "npx", "args": [ "mcp-remote", "https://mcp.apify.com/?tools=crawlerbros/un-comtrade-scraper", "--header", "Authorization: Bearer " ] } } } ``` ## OpenAPI specification ```json { "openapi": "3.0.1", "info": { "title": "UN Comtrade Scraper", "description": "Scrape UN Comtrade international trade statistics - bilateral trade flows, commodity data by HS/BEC/SITC codes, import/export values, weights, and quantities for any country pair.", "version": "1.0", "x-build-id": "VrlAn96JgvxIfmVlg" }, "servers": [ { "url": "https://api.apify.com/v2" } ], "paths": { "/acts/crawlerbros~un-comtrade-scraper/run-sync-get-dataset-items": { "post": { "operationId": "run-sync-get-dataset-items-crawlerbros-un-comtrade-scraper", "x-openai-isConsequential": false, "summary": "Executes an Actor, waits for its completion, and returns Actor's dataset items in response.", "tags": [ "Run Actor" ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/inputSchema" } } } }, "parameters": [ { "name": "token", "in": "query", "required": true, "schema": { "type": "string" }, "description": "Enter your Apify token here" } ], "responses": { "200": { "description": "OK" } } } }, "/acts/crawlerbros~un-comtrade-scraper/runs": { "post": { "operationId": "runs-sync-crawlerbros-un-comtrade-scraper", "x-openai-isConsequential": false, "summary": "Executes an Actor and returns information about the initiated run in response.", "tags": [ "Run Actor" ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/inputSchema" } } } }, "parameters": [ { "name": "token", "in": "query", "required": true, "schema": { "type": "string" }, "description": "Enter your Apify token here" } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/runsResponseSchema" } } } } } } }, "/acts/crawlerbros~un-comtrade-scraper/run-sync": { "post": { "operationId": "run-sync-crawlerbros-un-comtrade-scraper", "x-openai-isConsequential": false, "summary": "Executes an Actor, waits for completion, and returns the OUTPUT from Key-value store in response.", "tags": [ "Run Actor" ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/inputSchema" } } } }, "parameters": [ { "name": "token", "in": "query", "required": true, "schema": { "type": "string" }, "description": "Enter your Apify token here" } ], "responses": { "200": { "description": "OK" } } } } }, "components": { "schemas": { "inputSchema": { "type": "object", "required": [ "mode" ], "properties": { "mode": { "title": "Mode", "enum": [ "getCommodityTrade", "listReporters" ], "type": "string", "description": "What to fetch: trade data for a commodity, or a list of valid reporter countries.", "default": "getCommodityTrade" }, "typeCode": { "title": "Trade Type", "enum": [ "C", "S" ], "type": "string", "description": "Commodity (goods) or Service trade.", "default": "C" }, "freqCode": { "title": "Frequency", "enum": [ "A", "M" ], "type": "string", "description": "Annual or Monthly data.", "default": "A" }, "clCode": { "title": "Classification System", "enum": [ "HS" ], "type": "string", "description": "Classification system for the commodity code. The public preview API only supports HS (Harmonized System). BEC and SITC require a paid API subscription.", "default": "HS" }, "reporterCode": { "title": "Reporter Country Code", "type": "string", "description": "Numeric ISO country code of the reporting country. Examples: 842=USA, 36=Australia, 826=UK, 156=China, 276=Germany, 392=Japan." }, "partnerCode": { "title": "Partner Country Code", "type": "string", "description": "Numeric ISO code for the trade partner. Use 0 for World (all partners aggregated). Examples: 0=World, 156=China, 842=USA, 276=Germany." }, "cmdCode": { "title": "Commodity Code (HS)", "type": "string", "description": "HS commodity code to filter by. Examples: 8471=computers, 2709=crude oil, 8703=passenger cars, TOTAL=all commodities, AG2=all 2-digit chapters." }, "period": { "title": "Period", "type": "string", "description": "Year for annual data (e.g. 2022) or year-month for monthly data (e.g. 202201 for January 2022)." }, "maxItems": { "title": "Max Items", "minimum": 1, "maximum": 500, "type": "integer", "description": "Maximum number of records to return. Public API limit is 500 per request.", "default": 100 } } }, "runsResponseSchema": { "type": "object", "properties": { "data": { "type": "object", "properties": { "id": { "type": "string" }, "actId": { "type": "string" }, "userId": { "type": "string" }, "startedAt": { "type": "string", "format": "date-time", "example": "2025-01-08T00:00:00.000Z" }, "finishedAt": { "type": "string", "format": "date-time", "example": "2025-01-08T00:00:00.000Z" }, "status": { "type": "string", "example": "READY" }, "meta": { "type": "object", "properties": { "origin": { "type": "string", "example": "API" }, "userAgent": { "type": "string" } } }, "stats": { "type": "object", "properties": { "inputBodyLen": { "type": "integer", "example": 2000 }, "rebootCount": { "type": "integer", "example": 0 }, "restartCount": { "type": "integer", "example": 0 }, "resurrectCount": { "type": "integer", "example": 0 }, "computeUnits": { "type": "integer", "example": 0 } } }, "options": { "type": "object", "properties": { "build": { "type": "string", "example": "latest" }, "timeoutSecs": { "type": "integer", "example": 300 }, "memoryMbytes": { "type": "integer", "example": 1024 }, "diskMbytes": { "type": "integer", "example": 2048 } } }, "buildId": { "type": "string" }, "defaultKeyValueStoreId": { "type": "string" }, "defaultDatasetId": { "type": "string" }, "defaultRequestQueueId": { "type": "string" }, "buildNumber": { "type": "string", "example": "1.0.0" }, "containerUrl": { "type": "string" }, "usage": { "type": "object", "properties": { "ACTOR_COMPUTE_UNITS": { "type": "integer", "example": 0 }, "DATASET_READS": { "type": "integer", "example": 0 }, "DATASET_WRITES": { "type": "integer", "example": 0 }, "KEY_VALUE_STORE_READS": { "type": "integer", "example": 0 }, "KEY_VALUE_STORE_WRITES": { "type": "integer", "example": 1 }, "KEY_VALUE_STORE_LISTS": { "type": "integer", "example": 0 }, "REQUEST_QUEUE_READS": { "type": "integer", "example": 0 }, "REQUEST_QUEUE_WRITES": { "type": "integer", "example": 0 }, "DATA_TRANSFER_INTERNAL_GBYTES": { "type": "integer", "example": 0 }, "DATA_TRANSFER_EXTERNAL_GBYTES": { "type": "integer", "example": 0 }, "PROXY_RESIDENTIAL_TRANSFER_GBYTES": { "type": "integer", "example": 0 }, "PROXY_SERPS": { "type": "integer", "example": 0 } } }, "usageTotalUsd": { "type": "number", "example": 0.00005 }, "usageUsd": { "type": "object", "properties": { "ACTOR_COMPUTE_UNITS": { "type": "integer", "example": 0 }, "DATASET_READS": { "type": "integer", "example": 0 }, "DATASET_WRITES": { "type": "integer", "example": 0 }, "KEY_VALUE_STORE_READS": { "type": "integer", "example": 0 }, "KEY_VALUE_STORE_WRITES": { "type": "number", "example": 0.00005 }, "KEY_VALUE_STORE_LISTS": { "type": "integer", "example": 0 }, "REQUEST_QUEUE_READS": { "type": "integer", "example": 0 }, "REQUEST_QUEUE_WRITES": { "type": "integer", "example": 0 }, "DATA_TRANSFER_INTERNAL_GBYTES": { "type": "integer", "example": 0 }, "DATA_TRANSFER_EXTERNAL_GBYTES": { "type": "integer", "example": 0 }, "PROXY_RESIDENTIAL_TRANSFER_GBYTES": { "type": "integer", "example": 0 }, "PROXY_SERPS": { "type": "integer", "example": 0 } } } } } } } } } } ```