faostat-mcp-server: query observations
faostat_query_observationsQuery a FAOSTAT domain's data cube by area(s), item(s), element(s), and year range, returning observations (area, item, element, year, value, unit, and the data-quality flag). Resolve codes first with faostat_resolve_codes — the cube is unqueryable without them. Aggregate regions (World, continents, economic groupings) are EXCLUDED by default so a naive SUM does not double-count a region with its member countries; set include_aggregates=true to get the regional roll-ups, or pass explicit area_codes to query exactly what you name. Small result sets return inline; large ones spill to a DataCanvas table (returned canvas_id + table_name) for GROUP BY / ranking / time-series analysis via faostat_dataframe_query. Every row carries its flag — commonly A=Official, B=time-series break, E=Estimated, I=Imputed, M=Missing (value cannot exist), T=Unofficial, X=from an international organization, plus others FAOSTAT defines per domain — so honor it, treat any unrecognized flag as informational, and never assume an estimated, imputed, or unrecognized value is official.
Input Schema
| Name | Required | Description | Default |
|---|---|---|---|
| limit | No | Max observations returned inline — also the preview size when the result stages to a canvas table. Rows past it are never dropped silently: a match larger than limit stages in full to a DataCanvas table (canvas_id + table_name), and when no table is staged the notice reports how many matched so you can raise limit or narrow the filters. Max 1000. | |
| domain | Yes | FAOSTAT domain code (e.g. "QCL"). Must be indexed locally. | |
| year_end | No | Inclusive end year (e.g. 2022). | |
| canvas_id | No | Canvas ID from a prior call to stage onto. Omit to start a fresh canvas (a new id is returned). | |
| area_codes | No | Area codes from faostat_resolve_codes. When set, aggregates are NOT auto-excluded — the codes are honored verbatim. | |
| item_codes | No | Item codes from faostat_resolve_codes. | |
| year_start | No | Inclusive start year (e.g. 2000). | |
| element_codes | No | Element codes from faostat_resolve_codes (e.g. 5510 Production). | |
| include_aggregates | No | When false (default), exclude aggregate-region rows (codes ≥ 5000 plus a few curated sub-threshold roll-ups such as China=351) so sums are not double-counted. Set true for World/continent/grouping roll-ups. Ignored when explicit area_codes are passed. |
Output Schema
| Name | Required | Description | Default |
|---|---|---|---|
| error | No | Present when the call failed. Absent on success. | |
| domain | No | The domain code echoed back. | |
| notice | No | Guidance on empty results, aggregate exclusion, or how to reach the spilled set. | |
| spilled | No | True when the full result was staged on a DataCanvas table. | |
| canvas_id | No | Canvas ID holding the staged result — pass to faostat_dataframe_query / _describe. | |
| truncated | No | True when the staged table hit the 50,000-row staging cap — the staged set is a PREFIX of the match, not the complete result. Partition the query by year or code ranges to capture the rest. | |
| table_name | No | Canvas table name holding the full result set (present when spilled). | |
| totalCount | No | Observations matched. Exact when the result was returned inline or fully staged. A floor — more matched — in two cases, both named by the notice: the match exceeded the 50,000-row staging cap (truncated is then true), or staging failed and the response fell back to an inline page. | |
| observations | No | Inline observations (preview when the full set spilled to a canvas table). | |
| staged_row_count | No | Rows actually staged on the canvas table (present when spilled). Equals the full match count unless truncated, in which case it is the 50,000-row cap. |