Lookup Countries / Areas
comtrade_lookup_countriesRead-only
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.
Input Schema
TableJSON Schema
| Name | Required | Description | Default |
|---|---|---|---|
| role | No | Filter by role: "reporter" returns only codes valid for the reporterCode parameter, "partner" returns only partner areas (includes regional groupings), "any" returns all matches regardless of role. | any |
| query | Yes | Country or area name fragment, full name, or ISO alpha-2/alpha-3 code to search for. Case-insensitive. Examples: "Germany", "DEU", "DE", "united states", "china". | |
| include_groups | No | Whether to include regional and economic groupings (e.g. EU, ASEAN). Set to false to return only individual countries. |
Output Schema
TableJSON Schema
| Name | Required | Description | Default |
|---|---|---|---|
| error | No | Present when the call failed. Absent on success. | |
| notice | No | Recovery hint when no matches are found — echoes the query and suggests alternatives. Absent when results are non-empty. | |
| matches | No | Country/area entries matching the query, sorted by name. | |
| totalMatches | No | Total number of matching entries. |