Compute U.S. Trade Balance With Countries
census_trade_get_trade_balanceCompute the U.S. trade balance (exports minus imports) for one or more countries in a single call, with optional HS commodity filtering. Returns per-country exports, imports, and balance in USD.
Instructions
Compute the U.S. trade balance (exports minus imports) with one or more countries or country groupings, for a given time period, in one call.
This is a workflow tool that combines an exports/hs query and an imports/hs query (which census_trade_query_exports/imports would otherwise require two separate calls to do), sums values across the requested period, and computes the balance per country plus a combined total.
Args:
countries (string[]): one or more CTY_CODE values, e.g. ["1220","2010"] for Canada and Mexico (use census_trade_lookup_country_code to find codes)
time (string, optional) or year+months (optional): time period, e.g. time="2024" is invalid - use time="from 2024-01 to 2024-12" or year="2024", months=["01",...,"12"]
hs_code (string, optional): restrict to a specific HS commodity code/prefix instead of total trade, e.g. "87" for vehicles
import_basis ('general' | 'consumption', default 'general'): which import total to use
response_format ('markdown' | 'json', default 'markdown')
Returns: Per-country exports, imports, and balance in USD, plus a combined total row. Positive balance = U.S. trade surplus with that country; negative = deficit.
Examples:
Use when: "What's the U.S. trade balance with China in 2024?" -> countries=["5700"], year="2024", months=["01",...,"12"]
Use when: "Compare our vehicle trade balance with Japan, Germany, and South Korea last year" -> countries=["5880","4280","5800"], hs_code="87", year="2023", months=[...]
Don't use when: You just need one direction's raw data - use census_trade_query_exports or census_trade_query_imports.
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'. | |
| months | No | 2-digit months, used with 'year' instead of 'time'. | |
| hs_code | No | Optional HS commodity code (or prefix, e.g. '87' for vehicles) to restrict the balance to a specific product instead of total trade. Applied as E_COMMODITY on the export side and I_COMMODITY on the import side. | |
| countries | Yes | One or more Census CTY_CODE values to compute a trade balance for (use census_trade_lookup_country_code to find codes), e.g. ['1220','2010'] for Canada and Mexico. A grouping code (e.g. '0003' for European Union) also works. | |
| import_basis | No | Which import total to use: 'general' imports (GEN_VAL_MO, the standard headline figure) or 'consumption' imports (CON_VAL_MO). | general |
| response_format | No | Output format: 'markdown' for a human-readable table, or 'json' for machine-readable structured data. | markdown |