Query U.S. Import Trade Data
census_trade_query_importsQuery monthly U.S. import statistics by commodity, country, state, or port from Census trade data. Use filters and time ranges to get detailed import figures.
Instructions
Query monthly U.S. import statistics (January 2010-present) from the Census International Trade Data API.
This is the general-purpose tool for pulling import 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. Import value fields typically start with GEN_ (general imports) or CON_ (imports for consumption) rather than ALL_ (which is export-only).
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","GEN_VAL_MO"]
time (string, optional): 'YYYY-MM' or 'from YYYY-MM to YYYY-MM'
year (string, optional) + months (string[], optional): alternative to 'time'
filters (object, optional): e.g. {"CTY_CODE":"5700"} for China, {"I_COMMODITY":"8471*"} for HS codes starting with 8471 (computers)
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. import from China in HS 8471 (computers) in March 2024?" -> dataset="hs", get=["I_COMMODITY","I_COMMODITY_LDESC","GEN_VAL_MO"], time="2024-03", filters={"CTY_CODE":"5700","I_COMMODITY":"8471*"}
Use when: "Total general imports by state, Q1 2023" -> dataset="statehs", get=["STATE","GEN_VAL_MO"], time="from 2023-01 to 2023-03"
Don't use when: You need export data - use census_trade_query_exports.
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 |