comtradeapicall Python Package

The API requires a subscription_key. It is best practice to store this in a .env file and load it using load_dotenv to avoid hardcoding credentials in your scripts.

from dotenv import load_dotenv
import os

load_dotenv()
subscription_key = os.getenv("SUBSCRIPTION_KEY")

You can install the package directly from PyPI using pip.

Prerequisites

• Python 3.7
• Dependencies: If installing from source, run pip install -r requirements.txt to install necessary dependencies.

pip install comtradeapicall

To use the UN Comtrade API in a Python environment (such as a Jupyter kernel), install the comtradeapicall package via pip. It is also recommended to install pandas, matplotlib, load_dotenv, and plotly for data manipulation and visualization.

# Install the package and common dependencies
python -m pip install --upgrade comtradeapicall
python -m pip install pandas matplotlib load_dotenv plotly

The UN Comtrade API allows complex queries using specific syntax in the string parameters for reporterCode, partnerCode, cmdCode, and period:

1. Combining Entities (+): Use the plus sign to treat multiple country codes as a single aggregate group. Example: reporterCode = '392+156' combines Japan and China.
2. Multiple Queries (,): Use a comma to request data for multiple distinct entities in a single API call. Example: reporterCode = '276, 842' requests data for Germany and the USA separately.
3. Period Ranges (+): Use a plus sign to combine years. Example: period = '2022+2023'.

Refer to the official country groups JSON for valid codes.

To use the comtradeapicall package, you need to install it along with pandas for data manipulation and matplotlib for visualization. If you are working in a Jupyter environment, you can use the following commands:

# Install comtradeapicall package
pip install --upgrade comtradeapicall
# Install dependencies
pip install pandas matplotlib

The API requires a subscription key obtained from comtradedeveloper.un.org. It is recommended to store this key in a .env file and load it using python-dotenv to avoid hardcoding credentials.

from dotenv import load_dotenv
import os

load_dotenv()
subscription_key = os.getenv("SUBSCRIPTION_KEY")

The API requires a subscription key obtained from comtradedeveloper.un.org. It is recommended to store this key in a .env file and load it using python-dotenv to avoid hardcoding credentials.

from dotenv import load_dotenv
import os

load_dotenv()
subscription_key = os.getenv("SUBSCRIPTION_KEY")

To avoid API timeouts when requesting monthly data, generate a list of periods and convert them into a single string delimited by commas. This allows the API to process the request in manageable chunks.

from datetime import datetime
import pandas as pd

current_year = datetime.now().year
period_start = f"{current_year - 1}-01-01"
period_end = f"{current_year}-12-01"

# Generate monthly periods
periods = pd.date_range(period_start, period_end, freq='MS').strftime("%Y%m").tolist()

# Convert to comma-delimited string
delim = ","
temp = list(map(str, periods))
period_string = delim.join(temp)

For very large datasets (up to 2.5M records), use the Async component to submit jobs that run in the background and notify you via email upon completion.

Async Workflow

1. Submit: Use submitAsyncFinalDataRequest(subscription_key, SelectionCriteria, query_option) or submitAsyncTarifflineDataRequest(...) to start a job.
2. Check Status: Use checkAsyncDataRequest(subscription_key, [batchId]) to monitor progress.
3. Download: Use downloadAsyncFinalDataRequest(subscription_key, directory, SelectionCriteria, query_option) or downloadAsyncTarifflineDataRequest(...) to submit, wait, and download the resulting file.