Census API

Census International Trade API with Python

The Census International Trade API provides access to detailed U.S. import and export data by country, commodity, and time period. This tutorial demonstrates how to retrieve export data and identify top U.S. trading partners.

Background

International Trade Statistics

The Census Bureau collects data on U.S. merchandise trade through customs declarations. The international trade dataset includes monthly statistics on exports and imports by partner country and product category.

Key Variables

The main variables we'll use are:

• CTY_CODE - Country code identifying the trading partner. Codes 1000-8000 represent individual countries (excluding regional aggregates).
• CTY_NAME - Country name for display purposes.
• ALL_VAL_MO - Total value of exports for the month in U.S. dollars.

The full list of variables is available in the API documentation.

Example: Top U.S. Export Partners

Import the required packages and load your Census API key from a local config file (see the Setup guide for details). You can register for a free API key at the Census Bureau website.

In[1]:

import requests
import pandas as pd
import matplotlib.pyplot as plt
import config

key = config.census_key

Construct the API request to retrieve export values by country for a specific month. The endpoint intltrade/exports/hs provides Harmonized System trade data.

In[2]:

url = 'https://api.census.gov/data/timeseries/intltrade/exports/hs'
params = {
    'get': 'CTY_CODE,CTY_NAME,ALL_VAL_MO',
    'key': key,
    'time': '2025-10'
}

data = requests.get(url, params=params).json()

The response contains a list of lists, with the first row being column headers:

In[3]:

data[:3]

Out[3]:

[['CTY_CODE', 'CTY_NAME', 'ALL_VAL_MO', 'time'],
 ['0001', 'OPEC', '5765070418', '2025-10'],
 ['0003', 'PACIFIC RIM', '35817684498', '2025-10']]

Convert to a DataFrame, filter to individual countries (codes 1000-8000), and convert values to numeric billions.

In[4]:

df = pd.DataFrame(data[1:], columns=data[0])

# Some codes are non-numeric (e.g. '-'); keep only numeric codes
df = df.loc[df['CTY_CODE'].str.isdigit()]
df['CTY_CODE'] = df['CTY_CODE'].astype(int)
df = df[(df['CTY_CODE'] >= 1000) & (df['CTY_CODE'] < 8000)]

# Convert to billions
df['ALL_VAL_MO'] = df['ALL_VAL_MO'].astype(float) / 1e9

Sort by export value and select the top 20 trading partners.

In[5]:

top20 = (df.sort_values('ALL_VAL_MO', ascending=True)
           .tail(20)
           .set_index('CTY_NAME')['ALL_VAL_MO'])

Plot a horizontal bar chart showing the top export destinations.

In[6]:

fig, ax = plt.subplots(figsize=(8, 8))
top20.plot(kind='barh', ax=ax, color='#4a7c59')
ax.set_xlabel('')
ax.set_ylabel('')
ax.axis('off')

# Add value labels
for i, (country, val) in enumerate(top20.items()):
    ax.text(-0.5, i, country, ha='right', va='center', fontsize=10)
    ax.text(val + 0.3, i, f'${val:.1f}B', ha='left', va='center', fontsize=10)

ax.set_title('Top 20 U.S. Export Destinations, October 2025\n', fontsize=12)
plt.tight_layout()
plt.show()

Out[6]:

Further Resources

• Census International Trade API — main documentation
• API Variables — full list of available fields
• Schedule B Codes — product classification codes for detailed commodity analysis
• Census API Part 1 — manufacturing data from the M3 survey