Tools (6)

get_trade_flow
top_partners
top_commodities
search_commodities
trade_balance
report_feedback

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")

Request Body

{
  "reporter": "NO",
  "partner": "NO",
  "commodity_code": "example"
}

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)

Request Body

{
  "reporter": "NO",
  "commodity_code": "example",
  "year": 1
}

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)

Request Body

{
  "reporter": "NO",
  "partner": "NO",
  "year": 1
}

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").

Request Body

{
  "query": "example"
}

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).

Request Body

{
  "reporter": "NO",
  "partner": "NO",
  "year": 1
}

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")

Request Body

{
  "feedback": "example"
}

Quick Start

Shell

curl -X POST "https://context.gnist.ai/rest/un-comtrade/get_trade_flow" \
  -H "Content-Type: application/json" \
  -H "Gnist-API-Key: YOUR_API_KEY" \
  -d '{"reporter": "example", "partner": "example", "commodity_code": "example"}'

Python

import httpx

resp = httpx.post(
    "https://context.gnist.ai/rest/un-comtrade/get_trade_flow",
    headers={"Gnist-API-Key": "YOUR_API_KEY"},
    json={
  "reporter": "example",
  "partner": "example",
  "commodity_code": "example"
},
)
print(resp.json())