{"openapi":"3.0.3","info":{"title":"Gnist Context — UN Comtrade","description":"International trade statistics — imports, exports, and commodity flows between countries.\n\n- **MCP endpoint:** `https://context.gnist.ai/mcp/un-comtrade/`\n- **Toolkit page:** `/toolkits/un-comtrade`\n- **Full API spec:** `/api/openapi.json`\n- **Get an API key:** `/signup`","version":"1.0.0","contact":{"name":"GnistAI","url":"https://gnist.ai"}},"servers":[{"url":"https://context.gnist.ai","description":"Production"}],"paths":{"/rest/un-comtrade/get_trade_flow":{"post":{"tags":["Economics"],"summary":"get_trade_flow","description":"Fetch bilateral trade flows between two countries for a commodity.\n\nData from UN Comtrade — 200+ countries, 6,000+ HS commodity codes, back to 1962.\n\nArgs:\n    reporter: Reporting country name or ISO numeric code (e.g., \"Germany\", \"276\").\n    partner: Partner country name or ISO numeric code (e.g., \"China\", \"156\").\n             Use \"World\" or \"0\" for global aggregates.\n    commodity_code: HS commodity code (e.g., \"8471\" for computers, \"27\" for fuels,\n                    \"TOTAL\" for all commodities). Use search_commodities to find codes.\n    year_from: Start year (e.g., 2018). If omitted, returns most recent year.\n    year_to: End year (e.g., 2022). If omitted, same as year_from.\n    flow: Trade direction — \"M\" (imports), \"X\" (exports), \"MX\" (both, default).\n\nReturns:\n    List of trade records with reporter, partner, commodity, flow, value (USD), and weight (kg).","operationId":"un_comtrade_get_trade_flow","responses":{"200":{"description":"Successful tool call","content":{"application/json":{"schema":{"type":"object"}}}},"404":{"description":"Server or tool not found"},"500":{"description":"Tool execution error"}},"security":[{"ApiKeyHeader":[]},{"ApiKeyQuery":[]}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"additionalProperties":false,"properties":{"reporter":{"description":"Reporting country name or ISO numeric code (e.g., \"Germany\", \"276\").","type":"string"},"partner":{"description":"Partner country name or ISO numeric code (e.g., \"China\", \"156\"). Use \"World\" or \"0\" for global aggregates.","type":"string"},"commodity_code":{"description":"HS commodity code (e.g., \"8471\" for computers, \"27\" for fuels, \"TOTAL\" for all commodities). Use search_commodities to find codes.","type":"string"},"year_from":{"anyOf":[{"type":"integer"},{"type":"null"}],"default":null,"description":"Start year (e.g., 2018). If omitted, returns most recent year."},"year_to":{"anyOf":[{"type":"integer"},{"type":"null"}],"default":null,"description":"End year (e.g., 2022). If omitted, same as year_from."},"flow":{"default":"MX","description":"Trade direction — \"M\" (imports), \"X\" (exports), \"MX\" (both, default).","type":"string"}},"required":["reporter","partner","commodity_code"],"type":"object"}}}}}},"/rest/un-comtrade/top_partners":{"post":{"tags":["Economics"],"summary":"top_partners","description":"Rank a country's top trading partners for a given commodity.\n\nArgs:\n    reporter: Reporting country name or ISO numeric code (e.g., \"Germany\", \"276\").\n    commodity_code: HS commodity code (e.g., \"87\" for vehicles). Use \"TOTAL\" for all trade.\n    year: Year (e.g., 2022).\n    flow: \"X\" for exports (default) or \"M\" for imports.\n    limit: Number of top partners to return (1–50, default 10).\n\nReturns:\n    Ranked list of trading partners by trade value with country name, code, and value (USD).","operationId":"un_comtrade_top_partners","responses":{"200":{"description":"Successful tool call","content":{"application/json":{"schema":{"type":"object"}}}},"404":{"description":"Server or tool not found"},"500":{"description":"Tool execution error"}},"security":[{"ApiKeyHeader":[]},{"ApiKeyQuery":[]}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"additionalProperties":false,"properties":{"reporter":{"description":"Reporting country name or ISO numeric code (e.g., \"Germany\", \"276\").","type":"string"},"commodity_code":{"description":"HS commodity code (e.g., \"87\" for vehicles). Use \"TOTAL\" for all trade.","type":"string"},"year":{"description":"Year (e.g., 2022).","type":"integer"},"flow":{"default":"X","description":"\"X\" for exports (default) or \"M\" for imports.","type":"string"},"limit":{"default":10,"description":"Number of top partners to return (1–50, default 10).","type":"integer"}},"required":["reporter","commodity_code","year"],"type":"object"}}}}}},"/rest/un-comtrade/top_commodities":{"post":{"tags":["Economics"],"summary":"top_commodities","description":"Rank the top commodities traded between two countries.\n\nArgs:\n    reporter: Reporting country name or ISO numeric code (e.g., \"Germany\", \"276\").\n    partner: Partner country name or ISO numeric code (e.g., \"China\", \"156\").\n    year: Year (e.g., 2022).\n    flow: \"X\" for exports (default) or \"M\" for imports.\n    limit: Number of top commodities to return (1–50, default 10).\n\nReturns:\n    Ranked list of commodities by trade value with HS code, description, and value (USD).","operationId":"un_comtrade_top_commodities","responses":{"200":{"description":"Successful tool call","content":{"application/json":{"schema":{"type":"object"}}}},"404":{"description":"Server or tool not found"},"500":{"description":"Tool execution error"}},"security":[{"ApiKeyHeader":[]},{"ApiKeyQuery":[]}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"additionalProperties":false,"properties":{"reporter":{"description":"Reporting country name or ISO numeric code (e.g., \"Germany\", \"276\").","type":"string"},"partner":{"description":"Partner country name or ISO numeric code (e.g., \"China\", \"156\").","type":"string"},"year":{"description":"Year (e.g., 2022).","type":"integer"},"flow":{"default":"X","description":"\"X\" for exports (default) or \"M\" for imports.","type":"string"},"limit":{"default":10,"description":"Number of top commodities to return (1–50, default 10).","type":"integer"}},"required":["reporter","partner","year"],"type":"object"}}}}}},"/rest/un-comtrade/search_commodities":{"post":{"tags":["Economics"],"summary":"search_commodities","description":"Search for HS commodity codes by keyword.\n\nHelps find the right HS code to use with get_trade_flow, top_partners, and top_commodities.\n\nArgs:\n    query: Keyword to search (e.g., \"steel\", \"petroleum\", \"machinery\", \"vehicles\").\n\nReturns:\n    List of matching HS chapters (2-digit codes) with descriptions.","operationId":"un_comtrade_search_commodities","responses":{"200":{"description":"Successful tool call","content":{"application/json":{"schema":{"type":"object"}}}},"404":{"description":"Server or tool not found"},"500":{"description":"Tool execution error"}},"security":[{"ApiKeyHeader":[]},{"ApiKeyQuery":[]}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"additionalProperties":false,"properties":{"query":{"description":"Keyword to search (e.g., \"steel\", \"petroleum\", \"machinery\", \"vehicles\").","type":"string"}},"required":["query"],"type":"object"}}}}}},"/rest/un-comtrade/trade_balance":{"post":{"tags":["Economics"],"summary":"trade_balance","description":"Calculate bilateral trade balance between two countries.\n\nArgs:\n    reporter: Reporting country name or ISO numeric code (e.g., \"Germany\", \"276\").\n    partner: Partner country name or ISO numeric code (e.g., \"China\", \"156\").\n    year: Year (e.g., 2022).\n\nReturns:\n    Total exports, imports, and trade balance (exports minus imports) in USD.\n    Positive balance indicates a trade surplus; negative indicates a deficit.","operationId":"un_comtrade_trade_balance","responses":{"200":{"description":"Successful tool call","content":{"application/json":{"schema":{"type":"object"}}}},"404":{"description":"Server or tool not found"},"500":{"description":"Tool execution error"}},"security":[{"ApiKeyHeader":[]},{"ApiKeyQuery":[]}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"additionalProperties":false,"properties":{"reporter":{"description":"Reporting country name or ISO numeric code (e.g., \"Germany\", \"276\").","type":"string"},"partner":{"description":"Partner country name or ISO numeric code (e.g., \"China\", \"156\").","type":"string"},"year":{"description":"Year (e.g., 2022).","type":"integer"}},"required":["reporter","partner","year"],"type":"object"}}}}}},"/rest/un-comtrade/report_feedback":{"post":{"tags":["Economics"],"summary":"report_feedback","description":"Report a bug, feature request, or general feedback for this data source.\n\nUse this when something doesn't work as expected, when you'd like\na new feature, or when you have suggestions for improvement.\n\nArgs:\n    feedback: Describe the issue or suggestion.\n    feedback_type: One of 'bug', 'feature_request', or 'general'.","operationId":"un_comtrade_report_feedback","responses":{"200":{"description":"Successful tool call","content":{"application/json":{"schema":{"type":"object"}}}},"404":{"description":"Server or tool not found"},"500":{"description":"Tool execution error"}},"security":[{"ApiKeyHeader":[]},{"ApiKeyQuery":[]}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"additionalProperties":false,"properties":{"feedback":{"type":"string"},"feedback_type":{"default":"general","type":"string"}},"required":["feedback"],"type":"object"}}}}}}},"tags":[{"name":"Economics","description":"Data sources: Economics"}],"components":{"securitySchemes":{"ApiKeyHeader":{"type":"apiKey","in":"header","name":"gnist-api-key","description":"API key passed via request header."},"ApiKeyQuery":{"type":"apiKey","in":"query","name":"gnist_api_key","description":"API key passed via query parameter."}}}}