How to Automate UN Comtrade Data Extraction in Python: A Guide for Trade Analysts & Economics Students

How to Automate UN Comtrade Data Extraction in Python: A Guide for Trade Analysts & Economics Students

For international economics students, trade policy researchers, and market analysts, empirical work often begins with bilateral trade statistics. Whether analyzing trade elasticity, measuring tariff impacts, or calculating export market shares, the primary data source is almost always the United Nations Comtrade Database.

Historically, researchers have relied on the UN Comtrade web interface. However, manual downloads come with severe friction: strict query limits per session, fragmented annual CSV files, inconsistent country coding systems, and multi-header layouts that require tedious un-pivoting in Excel.

By leveraging the official UN Comtrade v1 API in Python, you can replace hours of manual spreadsheet formatting with a clean, reproducible script that pulls multi-year trade matrices directly into a Pandas DataFrame.

Prerequisites & Setup

The United Nations provides an official Python wrapper called comtradeapicall. To install it alongside Pandas, run the following in your terminal:

pip install comtradeapicall pandas

You will also need a free Primary Subscription Key from the UN Comtrade Developer Portal. Register for a free account, navigate to your profile, and copy your primary API key.

The 10-Line Extraction Script

Here is a complete, working Python script to extract annual bilateral merchandise trade flows across multiple years:

import comtradeapicall
import pandas as pd

# 1. Set your UN Comtrade API subscription key
subscription_key = "YOUR_PRIMARY_KEY_HERE"

# 2. Query 5 years of bilateral trade data
# typeCode: 'C' (Commodities) | freqCode: 'A' (Annual) | clCode: 'HS' (Harmonized System)
df = comtradeapicall.getFinalData(
    subscription_key,
    typeCode='C',
    freqCode='A',
    clCode='HS',
    period='2020,2021,2022,2023,2024',
    reporterCode='842',   # USA (ISO 3166-1 numeric code)
    partnerCode='156',    # China
    cmdCode='85',         # HS Chapter 85 (Electrical machinery & electronics)
    flowCode='M,X'        # M = Imports, X = Exports
)

# 3. Filter primary trade value and export clean CSV
clean_df = df[['period', 'reporterDesc', 'partnerDesc', 'cmdCode', 'flowDesc', 'primaryValue']]
clean_df.to_csv("bilateral_trade_clean.csv", index=False)
print(f"Extracted {len(clean_df)} records successfully.")
print(clean_df.head())

Understanding the Core API Parameters

Parameter Description Example Values
typeCode Trade type: Commodities ('C') or Services ('S') 'C'
freqCode Frequency: Annual ('A') or Monthly ('M') 'A'
clCode Classification system (HS, SITC, or BEC) 'HS'
period Comma-separated list of target years '2021,2022,2023,2024'
reporterCode Reporting nation's UN numeric country code '842' (USA), '156' (China)
cmdCode HS commodity heading (2, 4, or 6 digits) 'TOTAL' or '8517'

Why Programmatic Extraction Matters

Automating your trade data pipeline solves three major operational issues:

  1. Eliminates Manual Un-Pivoting: Downloaded portal spreadsheets often mix column totals with raw values. The API returns standardized schema with numeric values ready for statistical modeling.
  2. Reproducibility: Academic papers and industry reports require transparent methodologies. A Python script allows peers and clients to reproduce your exact dataset with a single command.
  3. Scalability: You can loop through all 97 HS chapters or an entire trading bloc (e.g., ASEAN, EU, AfCFTA) without clicking through hundreds of web pages.

Follow Automate Trades across our social channels for more practical automation scripts and workflows in international trade and economics.

Comments

Post a Comment

Popular posts from this blog

The Singapore Paradox: How an Island with No Natural Resources Captured 40% of Global Maritime Trade

Global Trade Case Study The Singapore Paradox: How an Island with Zero Natural Resources Captured 40% of Global Maritime Trade Why customs automation, single-window clearance, and trade velocity outperform physical commodity extraction every single time. Singapore GDP Per Capita $88,000+ Higher than US, UK & Germany Global Transshipment Share 40% World's #1 Transshipment Hub Customs Clearance Time < 10 Mins Down from 4 Days (1989) 1. The 1965 Eviction: A Nation with Nothing to Dig In August 1965, when Singapore was abruptly separated from the Federation of Malaysia, international consensus gave the newborn micro-state virtually zero probability of long-term economic survival. It possessed 710 square kilometers of tidal swamp, no agricultural hinterland, no mineral deposits, no oil wells, and had to i...
Read more

Automating Bill of Lading Data Extraction: ISO 6346 Validation & Zero-Data-Retention AI

Automating Bill of Lading Data Extraction: ISO 6346 Validation & Zero-Data-Retention AI In modern global logistics, the ocean Bill of Lading (B/L) serves as the definitive document of title, receipt of cargo, and contract of carriage. Yet across freight forwarding branches, customs brokerages, and port terminals, handling this critical document remains one of the most labor-intensive manual bottlenecks in the supply chain. Every day, logistics coordinators spend hundreds of cumulative hours manually re-keying data from crooked, 200 DPI scanned PDFs and multi-carrier manifests into enterprise Transportation Management Systems (TMS) and ERPs. Beyond operational fatigue, manual transcription is the leading cause of maritime documentation clerical errors. The High Cost of Documentation Typos: The $300/Day Demurrage Risk A single mistyped character in a container serial number or customs seal code can halt automated customs pre-clearance dead in its tracks. When manifest da...
Read more

The Trade Analyst's Guide to HS Code Classification with AI: Avoiding Hallucinations & Audit Penalties

The Trade Analyst's Guide to HS Code Classification with AI: Avoiding Hallucinations & Audit Penalties As generative AI tools become ubiquitous in corporate workflows, international trade analysts, freight forwarders, and customs compliance officers are increasingly testing large language models (LLMs) to classify commercial cargo. However, relying on raw AI outputs for full customs declarations represents one of the most dangerous operational traps in modern international trade. In customs compliance, an invented digit is not a minor typo—it is a legal violation that can trigger customs holds, mandatory audits, and severe tariff recalculations. The Structural Flaw: How the Harmonized System Actually Works The World Customs Organization (WCO) governs the Harmonized System internationally, but that standardization stops strictly at the 6-digit level : Digit Level Nomenclature Tier Governing Authority Consistency ...
Read more