faostat_get_data
Fetch statistical data from a FAOSTAT domain by specifying domain code and optional filters for area, item, element, and year.
Instructions
Fetch statistical data from a FAOSTAT domain. This is the primary tool for retrieving actual data values.
When you do not have an exact item, element, or area code, call faostat_search_codes first. If it returns requires_confirmation=True, you MUST ask the user to choose from the listed options before calling this tool.
IMPORTANT: For large domains, always filter by area/item/year to avoid very large responses. Check query size first with faostat_get_datasize.
IMPORTANT: Element codes used for filtering differ from the display codes returned in the response. Always use faostat_get_codes(dimension_id='element', domain_code=...) to get the correct filter codes. For example, in QCL:
Filter with element='2510' → response shows Element Code '5510' (Production)
Filter with element='2312' → response shows Element Code '5312' (Area harvested)
Args: domain_code: Domain code (e.g. 'QCL' for Crops and Livestock Products) lang: Language code (default: 'en') area: Country/area codes, comma-separated (e.g. '2' for Afghanistan). Use faostat_get_codes(dimension_id='area', domain_code=...) to find codes. element: Element FILTER codes, comma-separated (e.g. '2510' for Production, '2312' for Area harvested in QCL). These differ from the display codes in the response. Always look up via faostat_get_codes first. item: Item/commodity codes, comma-separated (e.g. '515' for Apples, '15' for Wheat) year: Year codes, comma-separated (e.g. '2020' or '2018,2019,2020') area_cs: Area code set name (alternative to individual area codes) element_cs: Element code set name item_cs: Item code set name year_cs: Year code set name (e.g. 'FAO_YEAR_RECENT' for recent years) show_codes: Include code columns in response (default: False — names are more useful for interpretation; codes are for filtering) show_unit: Include unit column in response (default: True) show_flags: Include data quality flags (default: False — rarely needed) null_values: Include rows with null values (default: False) limit: Maximum number of rows to return (default: 50). Set to 0 for no limit. Use faostat_get_datasize first if you expect a large result set. response_format: Output format (default: 'objects'). - 'objects': Array of self-describing JSON objects (best LLM comprehension) - 'compact': Columnar {"columns": [...], "rows": [[...]]} (~3x smaller) - 'csv': Plain CSV text with header row (~4x smaller) Use 'compact' or 'csv' when retrieving larger datasets to reduce token usage. fields: Comma-separated column names to include (e.g. 'Area,Year,Value'). Omit to include all columns. Use to reduce response size further.
Examples: # Apple production in Afghanistan 2024 (element 2510 = Production filter code) faostat_get_data('QCL', area='2', item='515', element='2510', year='2024')
# Food security indicators for all African countries
faostat_get_data('FS', area_cs='AFRICA')
# Minimal response — only area, year and value in CSV format
faostat_get_data('QCL', area='231', item='15', element='2510', year='2024',
response_format='csv', fields='Area,Year,Value')Input Schema
| Name | Required | Description | Default |
|---|---|---|---|
| domain_code | Yes | ||
| lang | No | en | |
| area | No | ||
| element | No | ||
| item | No | ||
| year | No | ||
| area_cs | No | ||
| element_cs | No | ||
| item_cs | No | ||
| year_cs | No | ||
| show_codes | No | ||
| show_unit | No | ||
| show_flags | No | ||
| null_values | No | ||
| limit | No | ||
| response_format | No | objects | |
| fields | No |
Output Schema
| Name | Required | Description | Default |
|---|---|---|---|
| result | Yes |