Rank Top Trading Partners
census_trade_get_top_partnersRank top U.S. trading partners by export or import value for a period or commodity. Returns each country's share and grand total.
Instructions
Return the top N countries ranked by U.S. export or import value for a given period and (optionally) a specific commodity - the Census API itself does not sort results, so this tool fetches the full country breakdown and sorts it for you.
Args:
direction ('exports' | 'imports'): rank by export destinations or import sources
dataset (string, default 'hs'): which classification dataset to pull from (see census_trade_list_datasets)
time (string, optional) or year+months (optional): time period
value_field (string, optional): value field to rank by, e.g. 'ALL_VAL_YR' for year-to-date exports. Defaults to ALL_VAL_MO (exports) or GEN_VAL_MO (imports).
filters (object, optional): extra filters, e.g. {"E_COMMODITY":"2709*"} to rank partners for crude oil exports only
top_n (number, default 10, max 50): how many partners to return
response_format ('markdown' | 'json', default 'markdown')
Returns: Ranked list with country, value in USD, and percentage share of total trade across all countries in the response, plus the grand total and count of countries with any trade.
Examples:
Use when: "Who are our top 5 export markets in 2024?" -> direction="exports", top_n=5, year="2024", months=[...]
Use when: "Which countries do we import the most crude oil from?" -> direction="imports", filters={"I_COMMODITY":"2709*"}, time="2024-06"
Don't use when: You want a two-way trade balance calculation - use census_trade_get_trade_balance instead.
Input Schema
| Name | Required | Description | Default |
|---|---|---|---|
| time | No | Time period as 'YYYY-MM' or a range 'from YYYY-MM to YYYY-MM'. Either 'time' or both 'year'+'months' is required. | |
| year | No | 4-digit year, used with 'months' instead of 'time'. | |
| top_n | No | How many top trading partners to return. | |
| months | No | 2-digit months, used with 'year' instead of 'time'. | |
| dataset | No | 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. | hs |
| 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). | |
| direction | Yes | 'exports' to rank countries by U.S. export value, 'imports' to rank by import value. | |
| value_field | No | Which value field to rank by, e.g. 'ALL_VAL_MO' (exports) or 'GEN_VAL_MO' (imports). Defaults to ALL_VAL_MO for exports and GEN_VAL_MO for imports if omitted. Use a *_YR variant for year-to-date figures. | |
| response_format | No | Output format: 'markdown' for a human-readable table, or 'json' for machine-readable structured data. | markdown |