Get Top Trade Commodities
comtrade_get_top_commoditiesRead-only
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.
Input Schema
TableJSON Schema
| Name | Required | Description | Default |
|---|---|---|---|
| limit | No | Maximum number of top commodity categories to return; above 50 returns all retrieved categories. | |
| period | Yes | Single period: annual (YYYY) or monthly (YYYYMM). | |
| flow_code | Yes | Trade flow: M=imports, X=exports. | |
| aggr_level | No | HS aggregation level: 2 = chapter (broader), 4 = heading (more specific). | |
| partner_code | No | M49 partner code to filter to a specific bilateral relationship. Omit to rank commodities across all partners. | |
| 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. | |
| flowCode | No | Flow direction queried. | |
| aggrLevel | No | HS aggregation level used. | |
| truncated | No | True when API returned 500 records and results may be incomplete. | |
| commodities | No | Top commodity categories sorted by descending trade value. | |
| reporterCode | No | M49 reporter code. | |
| reporterDesc | No | Reporter country name. | |
| totalValueUsd | No | Sum of primary values across all returned categories (before limit). | |
| totalCommodities | No | Total commodity categories returned by API. |