Resolve country and area names to Comtrade M49 numeric codes used in all data queries. Accepts a partial name, full name, or ISO alpha-2/alpha-3 code (e.g. "United States", "USA", "US"). Returns matching entries with their numeric code, ISO identifiers, and a validAsReporter flag — regional groupings like "World" (code 0) are valid partners but not valid reporters. Use this before any trade data tool that requires reporter_code or partner_code. To aggregate across all partners, use partner code 0 (World) — no lookup needed.
Find HS commodity codes by keyword, partial description, or known code prefix. Returns matched codes at the requested aggregation level (2-, 4-, or 6-digit) with full descriptions, parent code, leaf status, and a recommended_query_code field indicating the best code level for subsequent trade queries (2-digit chapter for broad analysis, 4- or 6-digit for specific products). This is the critical resolution step — agents cannot derive HS codes from product names without this tool. Use aggr_level 2 to start broad; narrow with aggr_level 4 or 6 once you have a chapter. To get all commodities for an entire chapter, pass the 2-digit code as cmd_code in trade tools.
List EBOPS 2010 service trade categories — the equivalent of comtrade_search_commodities for the services domain. Returns category codes, descriptions, and parent codes. Filter by keyword to find a specific service type (e.g. "transport", "financial", "travel"), or browse from a parent category code. Use the returned id as service_code in comtrade_get_services_trade.
Fetch bilateral trade flow records — the primary data retrieval tool. Returns trade value in USD (primaryValue — FOB for exports, CIF for imports), quantity, net weight, and period/commodity/partner metadata for each row. Accepts multiple periods and commodity codes per call; pass partner_code 0 to get totals aggregated across all partners. Omit cmd_code or pass "TOTAL" to aggregate all commodities. Free-tier capped at 500 records per call. Use comtrade_lookup_countries to resolve reporter/partner codes and comtrade_search_commodities to resolve HS codes before calling this tool.
Compute the trade balance for a country over one or more periods — total exports minus total imports — with optional commodity filter. Fetches export and import totals in parallel and returns the signed balance (USD), export value, import value, and coverage ratio (exports / imports). Note: mirror asymmetry is common — balance reflects values as reported by this country; the same flow may be recorded differently by the partner. Uses comtrade_lookup_countries to resolve reporter codes.
Rank trading partners for a reporter by trade value for a given commodity and flow direction. Returns the top N partners sorted by descending value — answers "who does country X mainly export product Y to?" or "where does country X mainly import product Z from?" for a single period. Fetches a disaggregated breakdown across all partners then sorts locally. Omit cmd_code to rank partners for total trade.
Rank commodity categories for a reporter by trade value for a given flow direction and period. Returns the top N HS chapters (2-digit) or headings (4-digit) sorted by descending value — answers "what does country X mainly export?" or "what does country X mainly import?". Symmetric counterpart to comtrade_get_top_partners. Optionally filter to a single partner country.
Check which reporter/period/classification combinations have published data before constructing expensive trade queries. Returns dataset records with period, classification, record count, and publication date. Call this before querying recent periods — annual data is typically published 3–12 months after the reference year and not all countries report every year. Omit all parameters to browse the full availability index.
Fetch international trade-in-services data (EBOPS 2010 classification). Same bilateral structure as goods trade: returns flow value in USD, period, and reporter/partner/category metadata for each row. Use comtrade_list_service_categories to find the right service code before querying. Note: services trade data has more limited country and period coverage than goods trade.