Query U.S. Export Trade Data
census_trade_query_exportsRetrieve U.S. export data for specific commodities, countries, districts, states, or ports, with customizable measures and time ranges.
Instructions
Query monthly U.S. export statistics (January 2010-present) from the Census International Trade Data API.
This is the general-purpose tool for pulling export data by commodity (HS/NAICS/End-Use/SITC/USDA/Hi-Tech), country, customs district, state, or port, for any combination of value/quantity/weight measures.
Args:
dataset (string): which classification/geography dataset, e.g. 'hs' for Harmonized System (see census_trade_list_datasets)
get (string[]): variable names to return as columns, e.g. ["CTY_CODE","CTY_NAME","ALL_VAL_MO"]
time (string, optional): 'YYYY-MM' or 'from YYYY-MM to YYYY-MM'
year (string, optional) + months (string[], optional): alternative to 'time', e.g. year="2024", months=["01","02","03"]
filters (object, optional): e.g. {"CTY_CODE":"1220"} for Canada, {"E_COMMODITY":"0805*"} for HS codes starting with 0805 (citrus fruit)
comm_level (string, optional): e.g. "HS2" to get 2-digit HS totals instead of full detail
summary_level (string, optional): "DET" for individual countries only, "CGP" for country groupings only
limit (number, default 100): max rows returned
response_format ('markdown' | 'json', default 'markdown')
Best practices (per the Census API User Guide):
Prefer narrow queries: the Census API times out on very large requests (e.g. all countries x all HS10 codes). Add country/commodity/district filters, or split wildcard commodity queries (e.g. query "1*" then "2*" separately) and combine results yourself.
Descriptive text fields (CTY_NAME, DIST_NAME, E_COMMODITY_LDESC/I_COMMODITY_LDESC, NAICS_LDESC, SITC_LDESC, etc.) require their matching code field (CTY_CODE, DISTRICT, E_COMMODITY/I_COMMODITY, NAICS, SITC) to also be in "get", or the API errors.
Only use commodity-classification parameters that match the chosen dataset (e.g. don't filter by NAICS on the "hs" dataset) - use census_trade_get_dataset_variables to check.
Results are NOT sorted by value; if you need a ranked list (e.g. top trading partners), use census_trade_get_top_partners instead, or sort the returned rows yourself.
A request that returns zero rows is not necessarily an error - it may just mean there was no trade for that combination of filters and time period.
Returns: Rows as either a markdown table or JSON, each row containing the fields requested in "get" plus "time".
Examples:
Use when: "What did the U.S. export to Germany in HS code 8703 (cars) in 2024?" -> dataset="hs", get=["E_COMMODITY","E_COMMODITY_LDESC","ALL_VAL_MO"], time="2024-01", filters={"CTY_CODE":"4280","E_COMMODITY":"8703*"}
Use when: "Show monthly export value trend for all countries, Jan-Jun 2023" -> get=["ALL_VAL_MO"], time="from 2023-01 to 2023-06"
Don't use when: You need import data - use census_trade_query_imports.
Don't use when: You want a country trade balance or a sorted list of top partners - use census_trade_get_trade_balance or census_trade_get_top_partners.
Input Schema
| Name | Required | Description | Default |
|---|---|---|---|
| get | Yes | Census API variable names to return as columns, e.g. ['CTY_CODE','CTY_NAME','ALL_VAL_MO']. Must be valid for the chosen dataset/direction - use get_dataset_variables to look them up. Descriptive text fields (e.g. CTY_NAME, DIST_NAME, E_COMMODITY_LDESC) require their matching code field (CTY_CODE, DISTRICT, E_COMMODITY) to also be included, or the API will error. | |
| time | No | Time period as 'YYYY-MM' (e.g. '2024-03') or a range 'from YYYY-MM to YYYY-MM'. Either 'time' or both 'year' and 'months' is required. | |
| year | No | 4-digit year, used with 'months' instead of 'time'. | |
| limit | No | Maximum number of rows to return (the tool fetches all matching rows from Census, then truncates to this limit client-side). | |
| months | No | 2-digit months (e.g. ['01','02']), used with 'year' instead of 'time'. | |
| dataset | Yes | Which commodity classification / geography dataset to query: 'hs' (Harmonized System, most detailed commodity codes, by country+district), 'naics' (industry classification, by country+district), 'enduse' (broad economic-use categories, by country+district), 'sitc' (Standard International Trade Classification, by country+district), 'usda' (agricultural vs. non-agricultural, by country+district), 'hitech' (Advanced Technology Products, by country+district), 'statehs' (HS codes by U.S. state instead of district, 2/4/6-digit only), 'statenaics' (NAICS by U.S. state instead of district, 2/3/4-digit only), 'porths' (HS codes by U.S. port instead of district, 2/4/6-digit only). Use list_trade_datasets for full descriptions. | |
| filters | No | Additional filter predicates as {VARIABLE_NAME: value}, e.g. {"CTY_CODE": "1220"} to filter to Canada, or {"CTY_CODE": ["1220","2010"]} for Canada OR Mexico. Commodity code filters accept a trailing '*' wildcard, e.g. {"E_COMMODITY": "01*"} for all HS codes starting with 01. Only use variable names valid for the chosen dataset/direction (check with get_dataset_variables). Do not mix commodity-classification parameters from different datasets in one call (e.g. do not filter by NAICS on the 'hs' dataset). | |
| comm_level | No | Commodity aggregation level, used with E_COMMODITY/I_COMMODITY, NAICS, or E_ENDUSE/I_ENDUSE fields. One of: HS2, HS4, HS6, HS10 (Harmonized System digit levels), NA2-NA6 (NAICS digit levels), MAN (total manufactured commodities, naics only), EU1, EU5 (End-Use digit levels). | |
| summary_level | No | 'DET' restricts results to individual trading partners; 'CGP' restricts results to country groupings (regions, trade blocs) instead of individual countries. Omit to receive both mixed together. | |
| response_format | No | Output format: 'markdown' for a human-readable table, or 'json' for machine-readable structured data. | markdown |