`comtrade_top_partners`

Pack: comtrade · Connect: https://pipeworx.io/mcp (see Connect below for a single-pack URL)

No MCP client? Call it directly: GET https://gateway.pipeworx.io/v1/tools/comtrade_top_partners for the schema, then POST the same URL with its arguments for the data.

Find a country’s top trading partners ranked by trade volume. Returns partner countries and total trade values. Defaults to ANNUAL; pass frequency=“monthly” for a single month’s ranking instead of the last full year’s.

Parameters

Name	Type	Required	Description
`reporter_code`	string	yes	Country name (e.g. “USA”, “China”) or UN numeric code (842=US). Names resolved automatically.
`year`	string	yes	Trade period. For frequency=“annual” (default): a year, e.g. “2024”. For frequency=“monthly”: year+month as YYYYMM, e.g. “202401”.
`flow`	string	yes	Trade flow: “M” for imports, “X” for exports
`hs_code`	string	no	Optional HS commodity code to filter by specific product (e.g. “2603” for copper ores) — omit for all commodities (TOTAL). Aliases accepted: commodity_code, commodity, hs, cmd_code (pass exactly one).
`commodity_code`	string	no	Alias for hs_code — HS commodity code (e.g. “2603” for copper ores). Use this OR hs_code, not both.
`commodity`	string	no	Alias for hs_code — HS commodity code. Use this OR hs_code, not both.
`hs`	string	no	Alias for hs_code — HS commodity code. Use this OR hs_code, not both.
`cmd_code`	string	no	Alias for hs_code — HS commodity code. Use this OR hs_code, not both.
`limit`	number	no	Number of top partners to return (default 20)
`frequency`	string	no	Data frequency: “annual” (default) or “monthly”. Monthly coverage is thinner — not every reporter files monthly, and recent months lag; a reporter with no filing for the requested month is absent from the ranking, not shown at zero. When “monthly”, pass `year` as YYYYMM.

Example call

Arguments

{
  "reporter_code": "842",
  "year": "2024",
  "flow": "X",
  "limit": 10
}

curl

curl -X POST https://gateway.pipeworx.io/comtrade/mcp \
  -H 'Content-Type: application/json' \
  -d '{"jsonrpc":"2.0","id":1,"method":"tools/call","params":{"name":"comtrade_top_partners","arguments":{"reporter_code":"842","year":"2024","flow":"X","limit":10}}}'

TypeScript (@pipeworx/sdk)

import { Pipeworx } from '@pipeworx/sdk';
const pipeworx = new Pipeworx();

const result = await pipeworx.call('comtrade_top_partners', {
  "reporter_code": "842",
  "year": "2024",
  "flow": "X",
  "limit": 10
});

More examples

{
  "reporter_code": "156",
  "year": "2023",
  "flow": "M"
}

{
  "reporter_code": "682",
  "year": "202401",
  "flow": "X",
  "frequency": "monthly",
  "limit": 5
}

{
  "reporter_code": "China",
  "year": "2024",
  "flow": "M",
  "commodity_code": "2603",
  "limit": 5
}

Response shape

Always returns: reporter, year, flow, total_partners, top_partners

Field	Type	Description
`reporter`	string	Reporting country name
`year`	string	Trade year queried
`flow`	string	Trade flow type (Imports or Exports)
`total_partners`	number	Total number of top partners returned
`top_partners`	array

Full JSON Schema

{
  "type": "object",
  "properties": {
    "reporter": {
      "type": "string",
      "description": "Reporting country name"
    },
    "year": {
      "type": "string",
      "description": "Trade year queried"
    },
    "flow": {
      "type": "string",
      "description": "Trade flow type (Imports or Exports)"
    },
    "total_partners": {
      "type": "number",
      "description": "Total number of top partners returned"
    },
    "top_partners": {
      "type": "array",
      "items": {
        "type": "object",
        "properties": {
          "rank": {
            "type": "number",
            "description": "Partner rank by trade value"
          },
          "partner": {
            "type": "string",
            "description": "Partner country name"
          },
          "partner_code": {
            "type": "number",
            "description": "Partner ISO numeric country code"
          },
          "trade_value_usd": {
            "type": "number",
            "description": "Trade value in USD"
          },
          "commodity": {
            "type": "string",
            "description": "Commodity code or description"
          }
        }
      }
    }
  },
  "required": [
    "reporter",
    "year",
    "flow",
    "total_partners",
    "top_partners"
  ]
}

Connect

Add this to your MCP client config — every tool in the catalog, including this one — or use one-click install buttons:

{
  "mcpServers": {
    "pipeworx": {
      "url": "https://pipeworx.io/mcp"
    }
  }
}

Connect to just the comtrade pack

{
  "mcpServers": {
    "comtrade": {
      "url": "https://gateway.pipeworx.io/comtrade/mcp"
    }
  }
}

See Getting Started for client-specific install steps.

comtrade_top_partners