Get Top Trading Partners
comtrade_get_top_partnersRead-only
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.
Input Schema
TableJSON Schema
| Name | Required | Description | Default |
|---|---|---|---|
| limit | No | Maximum number of top partners to return; above 50 returns all retrieved partners. | |
| period | Yes | Single period: annual (YYYY) or monthly (YYYYMM). | |
| cmd_code | No | Single HS commodity code (e.g. "84", "8471"). Omit or pass "TOTAL" to rank partners for total merchandise trade. | |
| flow_code | Yes | Trade flow: M=imports, X=exports. | |
| reporter_code | Yes | M49 numeric code of the reporting country. |
Output Schema
TableJSON Schema
| Name | Required | Description | Default |
|---|---|---|---|
| error | No | Present when the call failed. Absent on success. | |
| notice | No | Recovery hint when no data is returned. | |
| period | No | Period queried. | |
| cmdCode | No | Commodity code queried (TOTAL when omitted). | |
| flowCode | No | Flow direction queried. | |
| partners | No | Top partners sorted by descending trade value. | |
| truncated | No | True when API returned 500 records and results may be incomplete. | |
| reporterCode | No | M49 reporter code. | |
| reporterDesc | No | Reporter country name. | |
| totalPartners | No | Total partners with non-zero trade value returned by API. | |
| totalValueUsd | No | Sum of primary values across all returned partners (before limit truncation). |