Microproduct data guideintermediate

Census International Trade

Monthly U.S. import and export statistics for building commodity and partner trade monitors from a bounded Census extract.

Start the guide Open official source

At a glance

Difficulty
Intermediate — some data preparation helps
Size
Medium · ≤1 GB
Formats
JSON, CSV
Access
API
API key
Required
Provider
U.S. Census Bureau
Updates
Monthly
Data terms
U.S. Census Bureau API Terms of Service

From source to product signal

Test a product idea in four steps

The Census International Trade API returns monthly U.S. imports and exports by HS code and partner. Start with one commodity chapter, one month, and total partners. Values are revised, and a chapter total is not a shipment record.

1

Check the setup

  • Python 3.10 or newer
  • A notebook environment such as Jupyter or Google Colab
  • A free Census Data API key saved in the CENSUS_API_KEY environment variable
2

Access the data

  1. 1.Request a free key from the Census Data API page, or reuse an existing CENSUS_API_KEY.
  2. 2.Review the imports-by-HS examples on the International Trade dataset page.
  3. 3.Request one month of HS chapter 27 imports for all countries.
Open official source
3

Run the Python example

Install the packages, then run the notebook cell.

python -m pip install pandas requests

import os
import pandas as pd
import requests

response = requests.get(
    "https://api.census.gov/data/timeseries/intltrade/imports/hs",
    params={
        "get": "CTY_NAME,I_COMMODITY,GEN_VAL_MO",
        "YEAR": "2024",
        "MONTH": "12",
        "COMM_LVL": "HS2",
        "I_COMMODITY": "27",
        "key": os.environ["CENSUS_API_KEY"],
    },
    timeout=30,
)
response.raise_for_status()
rows = response.json()
trade = pd.DataFrame(rows[1:], columns=rows[0])
trade["GEN_VAL_MO"] = pd.to_numeric(trade["GEN_VAL_MO"], errors="coerce")
trade["retrieved_at_utc"] = pd.Timestamp.now(tz="UTC")
print(trade.head(20))
4

Test a useful signal

Rank mineral-fuel import partners for one month

Test whether a single HS chapter extract can power a bounded import-dependency monitor.

  1. 01Convert general import values to numbers and drop the WORLD total if it is present.
  2. 02Rank partner countries and keep the top ten.
  3. 03Explain that monthly totals are revised and that HS chapter 27 is not a retail energy price.

Dataset details

U.S. Census Bureau is a government source. Last verified 2026-08-17. Temporal coverage: 2010-present monthly statistics.

Theme

Markets & Economics

Domains

International EconomicsCommoditiesTrade

Data types

Time SeriesTabular

Tasks

Market MonitoringTrend AnalysisCountry Comparison

Geography

United States

Formats

JSONCSV

Provider

U.S. Census Bureau

Data terms

U.S. Census Bureau API Terms of Service