Tutorial: UN Comtrade - Gnist Context

Economics

Data source: UN Comtrade

Overview

UN Comtrade wraps UN Comtrade, handling authentication, pagination, and rate limits for you. This tutorial covers all 6 tools with working code examples you can copy and run.

Prerequisites

Sign up at https://context.gnist.ai/signup for a free API key (100 calls/day).
Choose your integration method: MCP protocol or REST API.

Connect via MCP

Add to your MCP client config (Claude Desktop, Cursor, etc.):

MCP Config

{
  "mcpServers": {
    "gnist-un-comtrade": {
      "url": "https://context.gnist.ai/mcp/un-comtrade/",
      "headers": {
        "Gnist-API-Key": "YOUR_API_KEY"
      }
    }
  }
}

Tools (6)

`get_trade_flow`

Fetch bilateral trade flows between two countries for a commodity. Data from UN Comtrade — 200+ countries, 6,000+ HS commodity codes, back to 1962. Args: reporter: Reporting country name or ISO numeric code (e.g., "Germany", "276"). partner: Partner country name or ISO numeric code (e.g., "China", "156"). Use "World" or "0" for global aggregates. commodity_code: HS commodity code (e.g., "8471" for computers, "27" for fuels, "TOTAL" for all commodities). Use search_commodities to find codes. year_from: Start year (e.g., 2018). If omitted, returns most recent year. year_to: End year (e.g., 2022). If omitted, same as year_from. flow: Trade direction — "M" (imports), "X" (exports), "MX" (both, default). Returns: List of trade records with reporter, partner, commodity, flow, value (USD), and weight (kg).

Parameter	Type	Required	Description
`reporter`	string	required	Reporting country name or ISO numeric code (e.g., "Germany", "276").
`partner`	string	required	Partner country name or ISO numeric code (e.g., "China", "156"). Use "World" or "0" for global aggregates.
`commodity_code`	string	required	HS commodity code (e.g., "8471" for computers, "27" for fuels, "TOTAL" for all commodities). Use search_commodities to find codes.
`year_from`	any	optional	Start year (e.g., 2018). If omitted, returns most recent year.
`year_to`	any	optional	End year (e.g., 2022). If omitted, same as year_from.
`flow`	string	optional	Trade direction — "M" (imports), "X" (exports), "MX" (both, default). (default: `MX`)

curl -X POST "https://context.gnist.ai/mcp/un-comtrade/" \
  -H "Content-Type: application/json" \
  -H "Gnist-API-Key: YOUR_API_KEY" \
  -d '{"jsonrpc": "2.0", "method": "tools/call", "id": 1, "params": {"name": "get_trade_flow", "arguments": {"reporter": "example", "partner": "example", "commodity_code": "example"}}}'

import httpx

resp = httpx.post(
    "https://context.gnist.ai/mcp/un-comtrade/",
    headers={"Gnist-API-Key": "YOUR_API_KEY"},
    json={'id': 1,
 'jsonrpc': '2.0',
 'method': 'tools/call',
 'params': {'arguments': {'commodity_code': 'example',
                          'partner': 'example',
                          'reporter': 'example'},
            'name': 'get_trade_flow'}},
)
print(resp.json())

`top_partners`

Rank a country's top trading partners for a given commodity. Args: reporter: Reporting country name or ISO numeric code (e.g., "Germany", "276"). commodity_code: HS commodity code (e.g., "87" for vehicles). Use "TOTAL" for all trade. year: Year (e.g., 2022). flow: "X" for exports (default) or "M" for imports. limit: Number of top partners to return (1–50, default 10). Returns: Ranked list of trading partners by trade value with country name, code, and value (USD).

Parameter	Type	Required	Description
`reporter`	string	required	Reporting country name or ISO numeric code (e.g., "Germany", "276").
`commodity_code`	string	required	HS commodity code (e.g., "87" for vehicles). Use "TOTAL" for all trade.
`year`	integer	required	Year (e.g., 2022).
`flow`	string	optional	"X" for exports (default) or "M" for imports. (default: `X`)
`limit`	integer	optional	Number of top partners to return (1–50, default 10). (default: `10`)

curl -X POST "https://context.gnist.ai/mcp/un-comtrade/" \
  -H "Content-Type: application/json" \
  -H "Gnist-API-Key: YOUR_API_KEY" \
  -d '{"jsonrpc": "2.0", "method": "tools/call", "id": 1, "params": {"name": "top_partners", "arguments": {"reporter": "example", "commodity_code": "example", "year": 2025}}}'

import httpx

resp = httpx.post(
    "https://context.gnist.ai/mcp/un-comtrade/",
    headers={"Gnist-API-Key": "YOUR_API_KEY"},
    json={'id': 1,
 'jsonrpc': '2.0',
 'method': 'tools/call',
 'params': {'arguments': {'commodity_code': 'example',
                          'reporter': 'example',
                          'year': 2025},
            'name': 'top_partners'}},
)
print(resp.json())

`top_commodities`

Rank the top commodities traded between two countries. Args: reporter: Reporting country name or ISO numeric code (e.g., "Germany", "276"). partner: Partner country name or ISO numeric code (e.g., "China", "156"). year: Year (e.g., 2022). flow: "X" for exports (default) or "M" for imports. limit: Number of top commodities to return (1–50, default 10). Returns: Ranked list of commodities by trade value with HS code, description, and value (USD).

Parameter	Type	Required	Description
`reporter`	string	required	Reporting country name or ISO numeric code (e.g., "Germany", "276").
`partner`	string	required	Partner country name or ISO numeric code (e.g., "China", "156").
`year`	integer	required	Year (e.g., 2022).
`flow`	string	optional	"X" for exports (default) or "M" for imports. (default: `X`)
`limit`	integer	optional	Number of top commodities to return (1–50, default 10). (default: `10`)

curl -X POST "https://context.gnist.ai/mcp/un-comtrade/" \
  -H "Content-Type: application/json" \
  -H "Gnist-API-Key: YOUR_API_KEY" \
  -d '{"jsonrpc": "2.0", "method": "tools/call", "id": 1, "params": {"name": "top_commodities", "arguments": {"reporter": "example", "partner": "example", "year": 2025}}}'

import httpx

resp = httpx.post(
    "https://context.gnist.ai/mcp/un-comtrade/",
    headers={"Gnist-API-Key": "YOUR_API_KEY"},
    json={'id': 1,
 'jsonrpc': '2.0',
 'method': 'tools/call',
 'params': {'arguments': {'partner': 'example',
                          'reporter': 'example',
                          'year': 2025},
            'name': 'top_commodities'}},
)
print(resp.json())

`search_commodities`

Search for HS commodity codes by keyword. Helps find the right HS code to use with get_trade_flow, top_partners, and top_commodities. Args: query: Keyword to search (e.g., "steel", "petroleum", "machinery", "vehicles"). Returns: List of matching HS chapters (2-digit codes) with descriptions.

Parameter	Type	Required	Description
`query`	string	required	Keyword to search (e.g., "steel", "petroleum", "machinery", "vehicles").

curl -X POST "https://context.gnist.ai/mcp/un-comtrade/" \
  -H "Content-Type: application/json" \
  -H "Gnist-API-Key: YOUR_API_KEY" \
  -d '{"jsonrpc": "2.0", "method": "tools/call", "id": 1, "params": {"name": "search_commodities", "arguments": {"query": "renewable energy"}}}'

import httpx

resp = httpx.post(
    "https://context.gnist.ai/mcp/un-comtrade/",
    headers={"Gnist-API-Key": "YOUR_API_KEY"},
    json={'id': 1,
 'jsonrpc': '2.0',
 'method': 'tools/call',
 'params': {'arguments': {'query': 'renewable energy'},
            'name': 'search_commodities'}},
)
print(resp.json())

`trade_balance`

Calculate bilateral trade balance between two countries. Args: reporter: Reporting country name or ISO numeric code (e.g., "Germany", "276"). partner: Partner country name or ISO numeric code (e.g., "China", "156"). year: Year (e.g., 2022). Returns: Total exports, imports, and trade balance (exports minus imports) in USD. Positive balance indicates a trade surplus; negative indicates a deficit.

Parameter	Type	Required	Description
`reporter`	string	required	Reporting country name or ISO numeric code (e.g., "Germany", "276").
`partner`	string	required	Partner country name or ISO numeric code (e.g., "China", "156").
`year`	integer	required	Year (e.g., 2022).

curl -X POST "https://context.gnist.ai/mcp/un-comtrade/" \
  -H "Content-Type: application/json" \
  -H "Gnist-API-Key: YOUR_API_KEY" \
  -d '{"jsonrpc": "2.0", "method": "tools/call", "id": 1, "params": {"name": "trade_balance", "arguments": {"reporter": "example", "partner": "example", "year": 2025}}}'

import httpx

resp = httpx.post(
    "https://context.gnist.ai/mcp/un-comtrade/",
    headers={"Gnist-API-Key": "YOUR_API_KEY"},
    json={'id': 1,
 'jsonrpc': '2.0',
 'method': 'tools/call',
 'params': {'arguments': {'partner': 'example',
                          'reporter': 'example',
                          'year': 2025},
            'name': 'trade_balance'}},
)
print(resp.json())

`report_feedback`

Report a bug, feature request, or general feedback for this data source. Use this when something doesn't work as expected, when you'd like a new feature, or when you have suggestions for improvement. Args: feedback: Describe the issue or suggestion. feedback_type: One of 'bug', 'feature_request', or 'general'.

Parameter	Type	Required	Description
`feedback`	string	required
`feedback_type`	string	optional	(default: `general`)

curl -X POST "https://context.gnist.ai/mcp/un-comtrade/" \
  -H "Content-Type: application/json" \
  -H "Gnist-API-Key: YOUR_API_KEY" \
  -d '{"jsonrpc": "2.0", "method": "tools/call", "id": 1, "params": {"name": "report_feedback", "arguments": {"feedback": "example"}}}'

import httpx

resp = httpx.post(
    "https://context.gnist.ai/mcp/un-comtrade/",
    headers={"Gnist-API-Key": "YOUR_API_KEY"},
    json={'id': 1,
 'jsonrpc': '2.0',
 'method': 'tools/call',
 'params': {'arguments': {'feedback': 'example'}, 'name': 'report_feedback'}},
)
print(resp.json())

Common Patterns

Search then retrieve
Use search_commodities to find items, then get_trade_flow to get full details. This two-step pattern is common for exploring data before drilling down.

Pagination
Several tools support limit, offset, or page parameters. Start with small limits during development, then increase for production queries.

FAQ

What data does UN Comtrade provide?

International trade statistics — imports, exports, and commodity flows between countries. It exposes 6 tools: get_trade_flow, top_partners, top_commodities, search_commodities, trade_balance, report_feedback.

What do I need to get started?

A Gnist API key (free tier: 100 calls/day). Sign up at https://context.gnist.ai/signup.

What format does the UN Comtrade API return?

JSON, via either MCP protocol (JSON-RPC 2.0) or REST API.