GnistAI GnistAI
Log in

Getting Started with FAOSTAT (FAO Food & Agriculture)

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.

All Tutorials   |   Overview   |   Playground   |   MCP   |   REST API   |   Home
Economics

Data source: FAOSTAT API

Overview

FAOSTAT (FAO Food & Agriculture) wraps FAOSTAT API, handling authentication, pagination, and rate limits for you. This tutorial covers all 7 tools with working code examples you can copy and run.

Prerequisites

  1. Sign up at https://context.gnist.ai/signup for a free API key (100 calls/day).
  2. 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-faostat": {
      "url": "https://context.gnist.ai/mcp/faostat/",
      "headers": {
        "Gnist-API-Key": "YOUR_API_KEY"
      }
    }
  }
}

Tools (7)

search_datasets

Search the FAOSTAT dataset catalog by keyword. Search across all FAO domains for datasets matching your query. FAOSTAT covers crop production, livestock, trade, prices, food security, land use, fertilizers, emissions, and more for 193+ countries. Args: query: Search term (e.g. "wheat", "rice", "food prices"). limit: Number of results to return (1-50, default 20). Returns: Matching datasets with domain codes needed for get_data calls.

ParameterTypeRequiredDescription
querystringrequiredSearch term for FAOSTAT datasets (e.g. "wheat", "rice production", "food prices", "fertilizer", "livestock").
limitintegeroptionalNumber of results to return (1-50, default 20). (default: 20)
curl -X POST "https://context.gnist.ai/mcp/faostat/" \
  -H "Content-Type: application/json" \
  -H "Gnist-API-Key: YOUR_API_KEY" \
  -d '{"jsonrpc": "2.0", "method": "tools/call", "id": 1, "params": {"name": "search_datasets", "arguments": {"query": "wheat"}}}'
import httpx

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

list_datasets

List available FAOSTAT dataset groups and domains. Browse the full FAOSTAT catalog organized by topic group. Use this to discover available domains before querying data. Key groups: Production (QCL, QI, QV), Trade (TCL, TM), Prices (PP, CP), Food Security (FS), Food Balances (FBS), Emissions (GT, GCE). Args: group: Optional group name filter. Omit to list all datasets. limit: Maximum datasets to return (1-200, default 50). Returns: List of datasets with group and domain codes.

ParameterTypeRequiredDescription
groupanyoptionalOptional group filter (e.g. "Production", "Trade", "Prices", "Food Security", "Emissions"). Omit to list all.
limitintegeroptionalMaximum datasets to return (1-200, default 50). (default: 50)
curl -X POST "https://context.gnist.ai/mcp/faostat/" \
  -H "Content-Type: application/json" \
  -H "Gnist-API-Key: YOUR_API_KEY" \
  -d '{"jsonrpc": "2.0", "method": "tools/call", "id": 1, "params": {"name": "list_datasets", "arguments": {"group": "Production"}}}'
import httpx

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

get_domain_dimensions

Get available dimensions and filter options for a FAOSTAT domain. Shows what filters (area, element, item, year) are available for a dataset, so you know what parameters to pass to get_data. Use get_dimension_codes to see the valid values for each dimension. Args: domain: FAOSTAT domain code from list_datasets. Returns: List of dimensions with IDs and labels.

ParameterTypeRequiredDescription
domainstringrequiredFAOSTAT domain code (e.g. "QCL" for crops, "TCL" for trade, "PP" for prices, "FS" for food security). Use list_datasets to find codes.
curl -X POST "https://context.gnist.ai/mcp/faostat/" \
  -H "Content-Type: application/json" \
  -H "Gnist-API-Key: YOUR_API_KEY" \
  -d '{"jsonrpc": "2.0", "method": "tools/call", "id": 1, "params": {"name": "get_domain_dimensions", "arguments": {"domain": "QCL"}}}'
import httpx

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

get_dimension_codes

Get valid codes for a specific dimension of a FAOSTAT domain. Look up what area codes, element codes, item codes, or year values are valid for a domain. Use these codes in get_data filters. Common area codes: 231 (USA), 351 (China), 100 (India), 5000 (World). Common element codes vary by domain (e.g. 2510=Production quantity). Args: domain: FAOSTAT domain code. dimension: Dimension name (area, element, item, year, etc.). limit: Maximum codes to return (1-500, default 100). Returns: List of valid codes with labels and descriptions.

ParameterTypeRequiredDescription
domainstringrequiredFAOSTAT domain code (e.g. "QCL", "TCL", "PP").
dimensionstringrequiredDimension name (e.g. "area" for countries, "element" for indicators, "item" for commodities, "year" for time periods).
limitintegeroptionalMaximum codes to return (1-500, default 100). (default: 100)
curl -X POST "https://context.gnist.ai/mcp/faostat/" \
  -H "Content-Type: application/json" \
  -H "Gnist-API-Key: YOUR_API_KEY" \
  -d '{"jsonrpc": "2.0", "method": "tools/call", "id": 1, "params": {"name": "get_dimension_codes", "arguments": {"domain": "QCL", "dimension": "area"}}}'
import httpx

resp = httpx.post(
    "https://context.gnist.ai/mcp/faostat/",
    headers={"Gnist-API-Key": "YOUR_API_KEY"},
    json={'id': 1,
 'jsonrpc': '2.0',
 'method': 'tools/call',
 'params': {'arguments': {'dimension': 'area', 'domain': 'QCL'},
            'name': 'get_dimension_codes'}},
)
print(resp.json())

get_data

Fetch data from a FAOSTAT domain. Query any FAOSTAT dataset filtered by area (country/region), element (indicator), item (commodity), and year. Covers production, trade, prices, food security, land use, emissions, and more for 193+ countries from 1961 to present. Args: domain: FAOSTAT domain code. Use list_datasets to find codes. areas: FAO area codes. Omit for all areas. elements: Element codes for indicator type. items: Item codes for commodities. years: Year values. area_cs: Area coding system (M49, FAO, ISO2, ISO3). limit: Maximum records to return (1-2000, default 500). Returns: Data records with area, element, item, year, value, unit, and flags.

ParameterTypeRequiredDescription
domainstringrequiredFAOSTAT 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.
areasanyoptionalFAO area codes (e.g. ["231", "351", "5000"] for USA, China, World). Use get_dimension_codes to find codes. Omit for all areas.
elementsanyoptionalElement codes for the indicator type (e.g. ["2510"] for production quantity, ["2610"] for import quantity). Use get_dimension_codes to find valid codes.
itemsanyoptionalItem codes for commodities (e.g. ["15"] for wheat, ["27"] for rice). Use get_dimension_codes to find valid codes.
yearsanyoptionalYear values (e.g. ["2020", "2021", "2022"]). Omit for all available years.
area_csanyoptionalArea coding system: "M49" (default), "FAO", "ISO2", or "ISO3".
limitintegeroptionalMaximum records to return (1-2000, default 500). (default: 500)
curl -X POST "https://context.gnist.ai/mcp/faostat/" \
  -H "Content-Type: application/json" \
  -H "Gnist-API-Key: YOUR_API_KEY" \
  -d '{"jsonrpc": "2.0", "method": "tools/call", "id": 1, "params": {"name": "get_data", "arguments": {"domain": "QCL"}}}'
import httpx

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

compare_countries

Compare data across countries/regions for a FAOSTAT domain. Fetches the same indicator for multiple areas side by side. Useful for cross-country analysis of production, trade volumes, food prices, food security metrics, and more. Args: domain: FAOSTAT domain code. area_codes: FAO area codes to compare. Maximum 20. elements: Element codes to filter by. items: Item codes to filter by. years: Year values to filter by. area_cs: Area coding system. Returns: Data grouped by area for easy comparison.

ParameterTypeRequiredDescription
domainstringrequiredFAOSTAT domain code (e.g. "QCL", "FS", "PP").
area_codeslist[string]requiredFAO area codes to compare (e.g. ["231", "351", "100"] for USA, China, India). Maximum 20.
elementsanyoptionalElement codes to filter by.
itemsanyoptionalItem codes to filter by.
yearsanyoptionalYear values to filter by.
area_csanyoptionalArea coding system: "M49", "FAO", "ISO2", or "ISO3".
curl -X POST "https://context.gnist.ai/mcp/faostat/" \
  -H "Content-Type: application/json" \
  -H "Gnist-API-Key: YOUR_API_KEY" \
  -d '{"jsonrpc": "2.0", "method": "tools/call", "id": 1, "params": {"name": "compare_countries", "arguments": {"domain": "QCL", "area_codes": "[\"231\""}}}'
import httpx

resp = httpx.post(
    "https://context.gnist.ai/mcp/faostat/",
    headers={"Gnist-API-Key": "YOUR_API_KEY"},
    json={'id': 1,
 'jsonrpc': '2.0',
 'method': 'tools/call',
 'params': {'arguments': {'area_codes': '["231"', 'domain': 'QCL'},
            'name': 'compare_countries'}},
)
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'.

ParameterTypeRequiredDescription
feedbackstringrequired
feedback_typestringoptional (default: general)
curl -X POST "https://context.gnist.ai/mcp/faostat/" \
  -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/faostat/",
    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_datasets to find items, then get_domain_dimensions 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 FAOSTAT (FAO Food & Agriculture) provide?

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. It exposes 7 tools: search_datasets, list_datasets, get_domain_dimensions, get_dimension_codes, get_data, compare_countries, 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 FAOSTAT (FAO Food & Agriculture) API return?

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

Next Steps

Interactive Playground
Try tools in your browser — no setup required.
Full Reference
Complete docs for all 7 tools.

Related Tutorials

Economic Indicators
Tutorial
BLS (Bureau of Labor Statistics)
Tutorial
DST (Statistics Denmark)
Tutorial
ESCO (Skills & Occupations)
Tutorial
Eurostat
Tutorial
Commodity Prices
Tutorial