# UN Comtrade API Package

The `comtradeapicall` Python package provides a simplified interface to the UN Comtrade APIs, enabling developers to extract and download international trade data without needing to understand the complex API endpoints and parameters. The package wraps the official UN Comtrade API (https://comtradedeveloper.un.org) and returns data as pandas DataFrames for easy analysis and manipulation.

This package supports multiple data extraction methods including preview (free, limited records), full data retrieval (requires subscription key), bulk downloads, and asynchronous requests for large datasets. It handles both final trade data and tariff line data across various product classifications (HS, SITC) and time frequencies (annual, monthly). The package also provides utilities for metadata retrieval, data availability checking, and reference data lookups.

## Installation

```bash
pip install comtradeapicall
```

## Preview Final Trade Data (Free, No Key Required)

Extract trade data without a subscription key, limited to 500 records. Returns a pandas DataFrame with trade statistics including trade values, quantities, and partner information.

```python
import comtradeapicall

# Preview Australia's imports of commodity code 91 (clocks/watches) in May 2022
df = comtradeapicall.previewFinalData(
    typeCode='C',           # C = Goods, S = Services
    freqCode='M',           # M = Monthly, A = Annual
    clCode='HS',            # Classification: HS, SITC, etc.
    period='202205',        # YYYYMM for monthly, YYYY for annual
    reporterCode='36',      # Australia country code
    cmdCode='91',           # Commodity code
    flowCode='M',           # M = Imports, X = Exports
    partnerCode=None,       # All partners
    partner2Code=None,
    customsCode=None,
    motCode=None,           # Mode of transport
    maxRecords=500,
    format_output='JSON',
    aggregateBy=None,
    breakdownMode='classic',
    countOnly=None,
    includeDesc=True
)

print(df.head())
# Output columns: refYear, refMonth, reporterCode, reporterDesc, flowCode, flowDesc,
#                 partnerCode, partnerDesc, cmdCode, cmdDesc, primaryValue, etc.
```

## Preview Tariff Line Data (Free, No Key Required)

Extract detailed tariff line data at the most granular commodity level, limited to 500 records without subscription.

```python
import comtradeapicall

# Preview Australia's tariff line imports of commodities 90 and 91 from Indonesia in May 2022
df = comtradeapicall.previewTarifflineData(
    typeCode='C',
    freqCode='M',
    clCode='HS',
    period='202205',
    reporterCode='36',      # Australia
    cmdCode='91,90',        # Multiple commodity codes
    flowCode='M',           # Imports
    partnerCode='360',      # Indonesia
    partner2Code=None,
    customsCode=None,
    motCode=None,
    maxRecords=500,
    format_output='JSON',
    countOnly=None,
    includeDesc=True
)

print(f"Records retrieved: {len(df)}")
print(df[['cmdCode', 'cmdDesc', 'primaryValue', 'netWgt']].head())
```

## Get Final Trade Data (Subscription Required)

Retrieve up to 250,000 records of final trade data with a valid subscription key.

```python
import comtradeapicall

subscription_key = 'your-subscription-key-here'

# Get Australia's imports of commodities 90 and 91 from all partners in May 2022
df = comtradeapicall.getFinalData(
    subscription_key,
    typeCode='C',
    freqCode='M',
    clCode='HS',
    period='202205',
    reporterCode='36',
    cmdCode='91,90',
    flowCode='M',
    partnerCode=None,
    partner2Code=None,
    customsCode=None,
    motCode=None,
    maxRecords=2500,
    format_output='JSON',
    aggregateBy=None,
    breakdownMode='classic',
    countOnly=None,
    includeDesc=True
)

print(f"Total records: {len(df)}")
print(f"Total trade value: ${df['primaryValue'].sum():,.2f}")
```

## Get Tariff Line Data (Subscription Required)

Retrieve detailed tariff line data with subscription key, supporting up to 250,000 records.

```python
import comtradeapicall

subscription_key = 'your-subscription-key-here'

# Get Australia's tariff line imports of commodities 90 and 91 from Indonesia
df = comtradeapicall.getTarifflineData(
    subscription_key,
    typeCode='C',
    freqCode='M',
    clCode='HS',
    period='202205',
    reporterCode='36',
    cmdCode='91,90',
    flowCode='M',
    partnerCode='360',
    partner2Code=None,
    customsCode=None,
    motCode=None,
    maxRecords=2500,
    format_output='JSON',
    countOnly=None,
    includeDesc=True
)

print(df.columns.tolist())
```

## Multi-Period Data Extraction with Retry

Use underscore-prefixed functions to automatically loop through multiple periods with built-in retry logic.

```python
import comtradeapicall

subscription_key = 'your-subscription-key-here'

# Get data for multiple months automatically (comma-separated periods)
df = comtradeapicall._getFinalData(
    subscription_key,
    typeCode='C',
    freqCode='M',
    clCode='HS',
    period='202201,202202,202203,202204,202205',  # Multiple periods
    reporterCode='36',
    cmdCode='91',
    flowCode='M',
    partnerCode=None,
    partner2Code=None,
    customsCode=None,
    motCode=None,
    maxRecords=500,
    format_output='JSON',
    aggregateBy=None,
    breakdownMode='classic',
    countOnly=None,
    includeDesc=True
)

# Data for all specified months combined
print(df.groupby('period')['primaryValue'].sum())
```

## Get Trade Balance Data

Retrieve trade data in a balance layout with exports and imports side by side for comparison.

```python
import comtradeapicall

subscription_key = 'your-subscription-key-here'

# Get trade balance for Australia's total trade in May 2022
df = comtradeapicall.getTradeBalance(
    subscription_key,
    typeCode='C',
    freqCode='M',
    clCode='HS',
    period='202205',
    reporterCode='36',
    cmdCode='TOTAL',
    partnerCode=None
)

print(df[['partnerDesc', 'export', 'import', 'balance']].head(10))
```

## Get Bilateral Data with Mirror Comparison

Compare reported data with mirror data from trading partners to identify discrepancies.

```python
import comtradeapicall

subscription_key = 'your-subscription-key-here'

# Get bilateral export data for Australia, comparing with partner reports
df = comtradeapicall.getBilateralData(
    subscription_key,
    typeCode='C',
    freqCode='M',
    clCode='HS',
    period='202205',
    reporterCode='36',
    cmdCode='TOTAL',
    flowCode='X',           # Exports
    partnerCode=None
)

# Compare reported vs mirror values
print(df[['partnerDesc', 'reportedValue', 'mirrorValue', 'difference']].head())
```

## Get Trade Matrix Data

Access the trade matrix which includes official statistics complemented by estimates for comprehensive coverage.

```python
import comtradeapicall

subscription_key = 'your-subscription-key-here'

# Get world exports of SITC one-digit sections in 2024
df = comtradeapicall.getTradeMatrix(
    subscription_key,
    typeCode='C',
    freqCode='A',
    period='2024',
    reporterCode='0',       # World
    cmdCode='ag1',          # One-digit SITC sections
    flowCode='X',           # Exports
    partnerCode='0',        # World
    aggregateBy=None,
    includeDesc=True
)

print(df.head())
```

## Get Data Count

Get the actual count of records matching your criteria without downloading all data.

```python
import comtradeapicall

# Preview count (no subscription key)
df_count = comtradeapicall.previewCountFinalData(
    typeCode='C',
    freqCode='A',
    clCode='HS',
    period='2022',
    reporterCode='36',
    cmdCode=None,           # All commodities
    flowCode=None,          # All flows
    partnerCode=None,
    partner2Code=None,
    customsCode=None,
    motCode=None
)
print(f"Total records available: {df_count['count'].values[0]}")

# With subscription key
subscription_key = 'your-subscription-key-here'
df_count = comtradeapicall.getCountFinalData(
    subscription_key,
    typeCode='C',
    freqCode='A',
    clCode='HS',
    period='2022',
    reporterCode='36',
    cmdCode=None,
    flowCode=None,
    partnerCode=None,
    partner2Code=None,
    customsCode=None,
    motCode=None
)
```

## Check Data Availability

Query what data is available for specific criteria before downloading.

```python
import comtradeapicall
from datetime import date, timedelta

subscription_key = 'your-subscription-key-here'

# Check final data availability for 2021
df = comtradeapicall.getFinalDataAvailability(
    subscription_key,
    typeCode='C',
    freqCode='A',
    clCode='HS',
    period='2021',
    reporterCode=None       # All reporters
)
print(f"Countries with data: {len(df)}")
print(df[['reporterCode', 'reporterDesc', 'period']].head())

# Check tariff line data availability for June 2022
df_tariff = comtradeapicall.getTarifflineDataAvailability(
    subscription_key,
    typeCode='C',
    freqCode='M',
    clCode='HS',
    period='202206',
    reporterCode=None
)

# Check data availability released since last week
lastweek = date.today() - timedelta(days=7)
df_recent = comtradeapicall.getFinalDataAvailability(
    subscription_key,
    typeCode='C',
    freqCode='A',
    clCode='HS',
    period='2021',
    reporterCode=None,
    publishedDateFrom=lastweek,
    publishedDateTo=None
)
```

## Check Bulk Data Availability

Query available bulk download files for batch processing.

```python
import comtradeapicall

subscription_key = 'your-subscription-key-here'

# Check final bulk files availability for SITC Rev.1 in 2021
df = comtradeapicall.getFinalDataBulkAvailability(
    subscription_key,
    typeCode='C',
    freqCode='A',
    clCode='S1',            # SITC Rev.1
    period='2021',
    reporterCode=None
)

print(df[['reporterCode', 'reporterDesc', 'fileSize']].head())

# Check tariff line bulk files for June 2022
df_tariff = comtradeapicall.getTarifflineDataBulkAvailability(
    subscription_key,
    typeCode='C',
    freqCode='M',
    clCode='HS',
    period='202206',
    reporterCode=None
)
```

## Get Live Updates

Retrieve information about recent data releases and updates.

```python
import comtradeapicall

subscription_key = 'your-subscription-key-here'

# Get recent data releases
df = comtradeapicall.getLiveUpdate(subscription_key)

print("Recent releases:")
print(df[['reporterDesc', 'period', 'publicationDate']].head(10))
```

## Bulk Download Final Data Files

Download complete data files for offline processing with optional decompression.

```python
import comtradeapicall
from datetime import date, timedelta

subscription_key = 'your-subscription-key-here'
directory = '/path/to/download/folder'

# Download monthly France final data for January 2000
comtradeapicall.bulkDownloadFinalFile(
    subscription_key,
    directory,
    typeCode='C',
    freqCode='M',
    clCode='HS',
    period='200001',
    reporterCode='251',     # France
    decompress=True         # Extract .gz files
)
# Output: COMTRADE-FINAL-CM251200001HS[2023-01-03] downloaded
# Total of 1 file(s) downloaded

# Download all annual HS data released yesterday
yesterday = date.today() - timedelta(days=1)
comtradeapicall.bulkDownloadFinalFileDateRange(
    subscription_key,
    directory,
    typeCode='C',
    freqCode='A',
    clCode='HS',
    period=None,            # All periods
    reporterCode=None,      # All reporters
    decompress=True,
    publishedDateFrom=yesterday,
    publishedDateTo=None
)
```

## Bulk Download Tariff Line Files

Download detailed tariff line data files for comprehensive analysis.

```python
import comtradeapicall

subscription_key = 'your-subscription-key-here'
directory = '/path/to/download/folder'

# Download Morocco tariff line data for Q1 2000
comtradeapicall.bulkDownloadTarifflineFile(
    subscription_key,
    directory,
    typeCode='C',
    freqCode='M',
    clCode='HS',
    period='200001,200002,200003',
    reporterCode='504',     # Morocco
    decompress=True
)

# Download annual Morocco tariff line data for 2010
comtradeapicall.bulkDownloadTarifflineFile(
    subscription_key,
    directory,
    typeCode='C',
    freqCode='A',
    clCode='HS',
    period='2010',
    reporterCode='504',
    decompress=True
)
```

## Bulk Download and Combine Files

Download multiple files and combine them into a single output file.

```python
import comtradeapicall

subscription_key = 'your-subscription-key-here'
directory = '/path/to/download/folder'

# Download and combine final data files for France 2020
comtradeapicall.bulkDownloadAndCombineFinalFile(
    subscription_key,
    directory,
    typeCode='C',
    freqCode='M',
    clCode='HS',
    period='202001,202002,202003',
    reporterCode='251',
    decompress=True         # Output as .txt instead of .gz
)
# Output: COMBINED-COMTRADE-FINAL-CMHS-251-202001,202002,202003-[timestamp].txt

# Download and combine tariff line files
comtradeapicall.bulkDownloadAndCombineTarifflineFile(
    subscription_key,
    directory,
    typeCode='C',
    freqCode='M',
    clCode='HS',
    period='202201,202202,202203',
    reporterCode='504',
    decompress=False        # Keep as compressed .gz
)
```

## Submit Asynchronous Data Request

Submit large data requests (up to 2.5M records) for asynchronous processing with email notification.

```python
import comtradeapicall

subscription_key = 'your-subscription-key-here'

# Submit async final data request
result = comtradeapicall.submitAsyncFinalDataRequest(
    subscription_key,
    typeCode='C',
    freqCode='M',
    clCode='HS',
    period='202205',
    reporterCode='36',
    cmdCode='91,90',
    flowCode='M',
    partnerCode=None,
    partner2Code=None,
    customsCode=None,
    motCode=None,
    aggregateBy=None,
    breakdownMode='classic'
)

print(f"Request ID: {result['requestId']}")
# Output: Return message: Request accepted
# Request ID: 2f92dd59-9763-474c-b27c-4af9ce16d454

# Submit async tariff line request
result_tariff = comtradeapicall.submitAsyncTarifflineDataRequest(
    subscription_key,
    typeCode='C',
    freqCode='M',
    clCode='HS',
    period='202205',
    reporterCode=None,      # All reporters
    cmdCode='91,90',
    flowCode='M',
    partnerCode=None,
    partner2Code=None,
    customsCode=None,
    motCode=None
)
```

## Check Asynchronous Job Status

Monitor the status of submitted asynchronous data requests.

```python
import comtradeapicall

subscription_key = 'your-subscription-key-here'

# Check status of a specific batch
df = comtradeapicall.checkAsyncDataRequest(
    subscription_key,
    batchId='2f92dd59-9763-474c-b27c-4af9ce16d454'
)

print(df[['requestId', 'status', 'uri']].head())
# status: 'Pending', 'Processing', 'Completed', 'Error'
```

## Download Async Data Request Results

Submit request, wait for completion, and automatically download the results.

```python
import comtradeapicall

subscription_key = 'your-subscription-key-here'
directory = '/path/to/download/folder'

# Submit final data request and auto-download when complete
comtradeapicall.downloadAsyncFinalDataRequest(
    subscription_key,
    directory,
    typeCode='C',
    freqCode='M',
    clCode='HS',
    period='202209',
    reporterCode=None,
    cmdCode='91,90',
    flowCode='M',
    partnerCode=None,
    partner2Code=None,
    customsCode=None,
    motCode=None
)
# Output: Processing and downloading the result. BatchId: abc123...
# Batch Status: Pending
# Batch Status: Processing
# Batch Status: Completed
# abc123.gz downloaded successfully

# Submit tariff line request and auto-download
comtradeapicall.downloadAsyncTarifflineDataRequest(
    subscription_key,
    directory,
    typeCode='C',
    freqCode='M',
    clCode='HS',
    period='202209',
    reporterCode=None,
    cmdCode='91,90',
    flowCode='M',
    partnerCode=None,
    partner2Code=None,
    customsCode=None,
    motCode=None
)
```

## Get Metadata and Publication Notes

Retrieve metadata and publication notes for trade datasets.

```python
import comtradeapicall

subscription_key = 'your-subscription-key-here'

# Get all metadata and publication notes for May 2022
df = comtradeapicall.getMetadata(
    subscription_key,
    typeCode='C',
    freqCode='M',
    clCode='HS',
    period='202205',
    reporterCode=None,
    showHistory=True        # Include historical publications
)

print(df[['datasetCode', 'publicationDate', 'isLatestPublication']].head())

# Get only latest publications
df_latest = comtradeapicall.getMetadata(
    subscription_key,
    typeCode='C',
    freqCode='M',
    clCode='HS',
    period='202205',
    reporterCode=None,
    showHistory=False
)
```

## List Reference Tables

Get a list of all available reference tables for codes and classifications.

```python
import comtradeapicall

# List all reference tables
df = comtradeapicall.listReference()
print(df[['category', 'description']].head(20))

# List references for a specific category
df_b5 = comtradeapicall.listReference('cmd:B5')
print(df_b5)
```

## Get Reference Data

Download specific reference tables for code lookups.

```python
import comtradeapicall

# Get reporter (country) reference data
df_reporters = comtradeapicall.getReference('reporter')
print(df_reporters[['id', 'text', 'entryEffectiveDate']].head())

# Get partner reference data
df_partners = comtradeapicall.getReference('partner')
print(f"Total partners: {len(df_partners)}")

# Get commodity classification reference
df_hs = comtradeapicall.getReference('cmd:HS')
print(df_hs.head())
```

## Convert Country ISO3 Codes to Comtrade Codes

Utility function to convert ISO3 country codes to UN Comtrade numeric codes.

```python
import comtradeapicall

# Convert multiple ISO3 codes to Comtrade codes
country_codes = comtradeapicall.convertCountryIso3ToCode('USA,FRA,CHE,ITA')
print(f"Comtrade codes: {country_codes}")
# Output: Comtrade codes: 842,251,757,381

# Use converted codes in data queries
subscription_key = 'your-subscription-key-here'
df = comtradeapicall.getFinalData(
    subscription_key,
    typeCode='C',
    freqCode='A',
    clCode='HS',
    period='2022',
    reporterCode=country_codes,
    cmdCode='TOTAL',
    flowCode='X',
    partnerCode=None,
    partner2Code=None,
    customsCode=None,
    motCode=None
)
```

## Get Standard Unit Values (SUV)

Retrieve Standard Unit Values for quality control and outlier detection in trade data.

```python
import comtradeapicall

subscription_key = 'your-subscription-key-here'

# Get SUV for commodity 010391 (live horses) in 2022, quantity unit: kg
df = comtradeapicall.getSUV(
    subscription_key,
    period='2022',
    cmdCode='010391',
    flowCode=None,          # All flows
    qtyUnitCode=8           # 8 = kilograms
)

print(df[['cmdCode', 'flowCode', 'suvLow', 'suv', 'suvHigh']].head())
```

## Using Proxy Server

All API functions support proxy server configuration for enterprise environments.

```python
import comtradeapicall

subscription_key = 'your-subscription-key-here'
proxy_url = 'http://proxy.company.com:8080'

# Use proxy with any function
df = comtradeapicall.getFinalData(
    subscription_key,
    typeCode='C',
    freqCode='A',
    clCode='HS',
    period='2022',
    reporterCode='36',
    cmdCode='TOTAL',
    flowCode='M',
    partnerCode=None,
    partner2Code=None,
    customsCode=None,
    motCode=None,
    proxy_url=proxy_url
)

# Works with bulk downloads too
comtradeapicall.bulkDownloadFinalFileDateRange(
    subscription_key,
    '/download/path',
    typeCode='C',
    freqCode='A',
    clCode='HS',
    period='2022',
    reporterCode='36',
    decompress=True,
    proxy_url=proxy_url
)
```

## Summary

The `comtradeapicall` package is designed for economists, trade analysts, researchers, and developers who need programmatic access to UN Comtrade's comprehensive international trade database. Primary use cases include trade flow analysis, bilateral trade comparisons, tariff line research, and building trade data pipelines. The package supports both ad-hoc data exploration through preview functions (no subscription required) and production-scale data extraction through subscription-based APIs with higher limits and asynchronous processing for large datasets.

Integration patterns typically involve using the preview functions for data discovery and prototyping, then switching to subscription-based functions for production workflows. For large-scale ETL processes, the bulk download functions with the combine option provide efficient batch processing, while asynchronous requests handle datasets exceeding standard limits. The package's pandas DataFrame return format enables seamless integration with data science workflows, visualization libraries, and database systems. All functions support proxy servers for enterprise deployment and include built-in retry logic for robust operation in production environments.