{"openapi":"3.0.3","info":{"title":"Gnist Context — FAOSTAT (FAO Food & Agriculture)","description":"FAO food and agriculture statistics — crop production, livestock, trade, prices, food security, land use, fertilizers, and emissions data for 193+ countries from 1961 to present.\n\n- **MCP endpoint:** `https://context.gnist.ai/mcp/faostat/`\n- **Toolkit page:** `/toolkits/faostat`\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/faostat/search_datasets":{"post":{"tags":["Economics"],"summary":"search_datasets","description":"Search the FAOSTAT dataset catalog by keyword.\n\nSearch across all FAO domains for datasets matching your query.\nFAOSTAT covers crop production, livestock, trade, prices, food\nsecurity, land use, fertilizers, emissions, and more for 193+ countries.\n\nArgs:\n    query: Search term (e.g. \"wheat\", \"rice\", \"food prices\").\n    limit: Number of results to return (1-50, default 20).\n\nReturns:\n    Matching datasets with domain codes needed for get_data calls.","operationId":"faostat_search_datasets","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":"Search term for FAOSTAT datasets (e.g. \"wheat\", \"rice production\", \"food prices\", \"fertilizer\", \"livestock\").","type":"string"},"limit":{"default":20,"description":"Number of results to return (1-50, default 20).","type":"integer"}},"required":["query"],"type":"object"}}}}}},"/rest/faostat/list_datasets":{"post":{"tags":["Economics"],"summary":"list_datasets","description":"List available FAOSTAT dataset groups and domains.\n\nBrowse the full FAOSTAT catalog organized by topic group. Use this\nto discover available domains before querying data. Key groups:\nProduction (QCL, QI, QV), Trade (TCL, TM), Prices (PP, CP),\nFood Security (FS), Food Balances (FBS), Emissions (GT, GCE).\n\nArgs:\n    group: Optional group name filter. Omit to list all datasets.\n    limit: Maximum datasets to return (1-200, default 50).\n\nReturns:\n    List of datasets with group and domain codes.","operationId":"faostat_list_datasets","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":false,"content":{"application/json":{"schema":{"additionalProperties":false,"properties":{"group":{"anyOf":[{"type":"string"},{"type":"null"}],"default":null,"description":"Optional group filter (e.g. \"Production\", \"Trade\", \"Prices\", \"Food Security\", \"Emissions\"). Omit to list all."},"limit":{"default":50,"description":"Maximum datasets to return (1-200, default 50).","type":"integer"}},"type":"object"}}}}}},"/rest/faostat/get_domain_dimensions":{"post":{"tags":["Economics"],"summary":"get_domain_dimensions","description":"Get available dimensions and filter options for a FAOSTAT domain.\n\nShows what filters (area, element, item, year) are available for\na dataset, so you know what parameters to pass to get_data.\nUse get_dimension_codes to see the valid values for each dimension.\n\nArgs:\n    domain: FAOSTAT domain code from list_datasets.\n\nReturns:\n    List of dimensions with IDs and labels.","operationId":"faostat_get_domain_dimensions","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":{"domain":{"description":"FAOSTAT domain code (e.g. \"QCL\" for crops, \"TCL\" for trade, \"PP\" for prices, \"FS\" for food security). Use list_datasets to find codes.","type":"string"}},"required":["domain"],"type":"object"}}}}}},"/rest/faostat/get_dimension_codes":{"post":{"tags":["Economics"],"summary":"get_dimension_codes","description":"Get valid codes for a specific dimension of a FAOSTAT domain.\n\nLook up what area codes, element codes, item codes, or year values\nare valid for a domain. Use these codes in get_data filters.\n\nCommon area codes: 231 (USA), 351 (China), 100 (India), 5000 (World).\nCommon element codes vary by domain (e.g. 2510=Production quantity).\n\nArgs:\n    domain: FAOSTAT domain code.\n    dimension: Dimension name (area, element, item, year, etc.).\n    limit: Maximum codes to return (1-500, default 100).\n\nReturns:\n    List of valid codes with labels and descriptions.","operationId":"faostat_get_dimension_codes","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":{"domain":{"description":"FAOSTAT domain code (e.g. \"QCL\", \"TCL\", \"PP\").","type":"string"},"dimension":{"description":"Dimension name (e.g. \"area\" for countries, \"element\" for indicators, \"item\" for commodities, \"year\" for time periods).","type":"string"},"limit":{"default":100,"description":"Maximum codes to return (1-500, default 100).","type":"integer"}},"required":["domain","dimension"],"type":"object"}}}}}},"/rest/faostat/get_data":{"post":{"tags":["Economics"],"summary":"get_data","description":"Fetch data from a FAOSTAT domain.\n\nQuery any FAOSTAT dataset filtered by area (country/region),\nelement (indicator), item (commodity), and year. Covers production,\ntrade, prices, food security, land use, emissions, and more\nfor 193+ countries from 1961 to present.\n\nArgs:\n    domain: FAOSTAT domain code. Use list_datasets to find codes.\n    areas: FAO area codes. Omit for all areas.\n    elements: Element codes for indicator type.\n    items: Item codes for commodities.\n    years: Year values.\n    area_cs: Area coding system (M49, FAO, ISO2, ISO3).\n    limit: Maximum records to return (1-2000, default 500).\n\nReturns:\n    Data records with area, element, item, year, value, unit, and flags.","operationId":"faostat_get_data","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":{"domain":{"description":"FAOSTAT domain code (e.g. \"QCL\" for crops/livestock, \"TCL\" for trade, \"PP\" for producer prices, \"FS\" for food security, \"FBS\" for food balances). Use list_datasets to find codes.","type":"string"},"areas":{"anyOf":[{"items":{"type":"string"},"type":"array"},{"type":"null"}],"default":null,"description":"FAO area codes (e.g. [\"231\", \"351\", \"5000\"] for USA, China, World). Use get_dimension_codes to find codes. Omit for all areas."},"elements":{"anyOf":[{"items":{"type":"string"},"type":"array"},{"type":"null"}],"default":null,"description":"Element codes for the indicator type (e.g. [\"2510\"] for production quantity, [\"2610\"] for import quantity). Use get_dimension_codes to find valid codes."},"items":{"anyOf":[{"items":{"type":"string"},"type":"array"},{"type":"null"}],"default":null,"description":"Item codes for commodities (e.g. [\"15\"] for wheat, [\"27\"] for rice). Use get_dimension_codes to find valid codes."},"years":{"anyOf":[{"items":{"type":"string"},"type":"array"},{"type":"null"}],"default":null,"description":"Year values (e.g. [\"2020\", \"2021\", \"2022\"]). Omit for all available years."},"area_cs":{"anyOf":[{"type":"string"},{"type":"null"}],"default":null,"description":"Area coding system: \"M49\" (default), \"FAO\", \"ISO2\", or \"ISO3\"."},"limit":{"default":500,"description":"Maximum records to return (1-2000, default 500).","type":"integer"}},"required":["domain"],"type":"object"}}}}}},"/rest/faostat/compare_countries":{"post":{"tags":["Economics"],"summary":"compare_countries","description":"Compare data across countries/regions for a FAOSTAT domain.\n\nFetches the same indicator for multiple areas side by side.\nUseful for cross-country analysis of production, trade volumes,\nfood prices, food security metrics, and more.\n\nArgs:\n    domain: FAOSTAT domain code.\n    area_codes: FAO area codes to compare. Maximum 20.\n    elements: Element codes to filter by.\n    items: Item codes to filter by.\n    years: Year values to filter by.\n    area_cs: Area coding system.\n\nReturns:\n    Data grouped by area for easy comparison.","operationId":"faostat_compare_countries","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":{"domain":{"description":"FAOSTAT domain code (e.g. \"QCL\", \"FS\", \"PP\").","type":"string"},"area_codes":{"description":"FAO area codes to compare (e.g. [\"231\", \"351\", \"100\"] for USA, China, India). Maximum 20.","items":{"type":"string"},"type":"array"},"elements":{"anyOf":[{"items":{"type":"string"},"type":"array"},{"type":"null"}],"default":null,"description":"Element codes to filter by."},"items":{"anyOf":[{"items":{"type":"string"},"type":"array"},{"type":"null"}],"default":null,"description":"Item codes to filter by."},"years":{"anyOf":[{"items":{"type":"string"},"type":"array"},{"type":"null"}],"default":null,"description":"Year values to filter by."},"area_cs":{"anyOf":[{"type":"string"},{"type":"null"}],"default":null,"description":"Area coding system: \"M49\", \"FAO\", \"ISO2\", or \"ISO3\"."}},"required":["domain","area_codes"],"type":"object"}}}}}},"/rest/faostat/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":"faostat_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."}}}}