Query data rows for a single WHO GHO indicator with optional spatial, temporal, and dimension filters. Returns rows with numeric values, uncertainty intervals (Low/High), and spatial/time metadata. This is the primary data-fetching tool in the find-then-query workflow: use who_search_indicators to find the indicator code, optionally call who_get_indicator_metadata to confirm which filter dimensions are valid, then call this tool. Discover positional filters from returned dim1Type/dim1, dim2Type/dim2 and dim3Type/dim3 pairs; metadata alone does not identify a slot. Spatial filters are mutually exclusive per call: provide only one of country_codes, region_codes, income_group_codes, or spatial_type — mixing them triggers an error. spatial_type selects any geography type rows carry in spatialDimType, including aggregates such as GLOBAL and WORLDBANKREGION; narrow it with spatial_codes. Omitting all spatial filters returns all geographies (may be large; use limit to cap). The sex filter only applies when the indicator uses SEX as its first cross-cutting dimension — on any other indicator the call fails with no_data; check who_get_indicator_metadata first if uncertain. Rows are returned in a deterministic order (most recent first by default), so a capped result is the top of a defined slice rather than an arbitrary sample; page through the rest with offset.
View input schema
{
"type": "object",
"properties": {
"indicator_code": {
"type": "string",
"minLength": 1,
"description": "Indicator code to query, e.g. \"WHOSIS_000001\". Use who_search_indicators to find codes."
},
"country_codes": {
"description": "WHO country codes to filter on, e.g. [\"JPN\",\"USA\",\"BRA\"], including historical codes such as ME1 and SDN736. Discover codes with who_list_dimension_values dimension=\"COUNTRY\". Mutually exclusive with region_codes, income_group_codes, and spatial_type.",
"type": "array",
"items": {
"type": "string",
"minLength": 1
}
},
"region_codes": {
"description": "WHO region codes to filter on, e.g. [\"AFR\",\"EUR\",\"AMR\",\"EMR\",\"SEAR\",\"WPR\"]. Returns the aggregate row for each named WHO region. For the world aggregate or another aggregate geography type, use spatial_type instead (e.g. spatial_type \"GLOBAL\"). To get country-level data for a region, use who_list_dimension_values with dimension=\"COUNTRY\" and parent_code set to the region code to retrieve WHO country codes, then pass those to country_codes. Use who_list_dimension_values with dimension=\"REGION\" to see all valid region codes. Mutually exclusive with country_codes, income_group_codes, and spatial_type.",
"type": "array",
"items": {
"type": "string",
"minLength": 1
}
},
"income_group_codes": {
"description": "World Bank income group codes, e.g. [\"WB_HI\",\"WB_LMI\",\"WB_LI\",\"WB_UMI\"]. Use who_list_dimension_values with dimension=\"WORLDBANKINCOMEGROUP\" to see all valid codes. Mutually exclusive with country_codes, region_codes, and spatial_type.",
"type": "array",
"items": {
"type": "string",
"minLength": 1
}
},
"spatial_type": {
"description": "Geography type to return, matched against the spatialDimType rows carry, e.g. \"GLOBAL\" for the world aggregate, \"WORLDBANKREGION\", \"UNSDGREGION\", or \"GBDREGION\". Alone it returns every row of that type; narrow it with spatial_codes. Passed through as given — a type the indicator does not carry returns no_data. Mutually exclusive with country_codes, region_codes, and income_group_codes. Empty strings are ignored with a notice.",
"type": "string"
},
"spatial_codes": {
"description": "Codes narrowing spatial_type to specific geographies, e.g. [\"WB_SSA\"] with spatial_type \"WORLDBANKREGION\". Requires spatial_type. Discover codes with who_list_dimension_values, passing the spatial type as the dimension. Empty arrays are ignored with a notice.",
"type": "array",
"items": {
"type": "string",
"minLength": 1
}
},
"year_from": {
"description": "Start year (inclusive) for the time range filter, e.g. 2015.",
"type": "integer",
"minimum": -9007199254740991,
"maximum": 9007199254740991
},
"year_to": {
"description": "End year (inclusive) for the time range filter, e.g. 2023.",
"type": "integer",
"minimum": -9007199254740991,
"maximum": 9007199254740991
},
"sex": {
"description": "Filter on sex dimension: SEX_BTSX (both sexes), SEX_FMLE (female), SEX_MLE (male). Only applies when the indicator uses SEX as its first cross-cutting dimension.",
"type": "string",
"enum": [
"SEX_BTSX",
"SEX_FMLE",
"SEX_MLE"
]
},
"dim1_value": {
"description": "Value filter for indicators whose first cross-cutting dimension is not SEX: the full prefixed code as returned in dim1, e.g. an AGEGROUP code like \"AGEGROUP_YEARS05-14\". Ignored when sex is also provided.",
"type": "string"
},
"dim2_value": {
"description": "Value filter for the second cross-cutting dimension: the full prefixed code as returned in dim2, e.g. AGEGROUP_DAYS0-27. Discover the position from returned dim2Type/dim2 pairs; metadata does not identify the slot. Empty strings are ignored with a notice.",
"type": "string"
},
"dim3_value": {
"description": "Value filter for the third cross-cutting dimension: the full prefixed code as returned in dim3, e.g. CHILDCAUSE_CH9. Discover the position from returned dim3Type/dim3 pairs; metadata does not identify the slot. Empty strings are ignored with a notice.",
"type": "string"
},
"data_source": {
"description": "Data-source filter for indicators that publish estimates from several surveys or sources for the same country, year, and sex: the full code, DATASOURCE_ prefix included, as returned in dataSourceDim or by who_list_dimension_values with dimension=\"DATASOURCE\", e.g. \"DATASOURCE_NLIS_312831\". Passed through as given — a code that matches no row returns no_data. Composes with any spatial filter. Empty strings are ignored with a notice.",
"type": "string"
},
"include_uncertainty": {
"default": true,
"description": "Include Low and High uncertainty interval bounds in output. Default true.",
"type": "boolean"
},
"limit": {
"default": 25,
"description": "Maximum number of data rows to return. Default 25, max 1000.",
"type": "integer",
"minimum": 1
},
"offset": {
"default": 0,
"description": "Zero-based row offset for pagination. Default 0. Pages are stable because rows are returned in a deterministic order — read hasMore and nextOffset from the response to continue. An offset at or beyond totalRows returns an empty rows array, not an error.",
"type": "integer",
"minimum": 0,
"maximum": 9007199254740991
},
"sort": {
"default": "year_desc",
"description": "Row ordering: \"year_desc\" (default) returns the most recent years first, \"year_asc\" the earliest first. Ties are broken by spatial code, then dimension, then row id.",
"type": "string",
"enum": [
"year_desc",
"year_asc"
]
}
},
"required": [
"indicator_code"
],
"$schema": "https://json-schema.org/draft/2020-12/schema",
"additionalProperties": false
}