Fetch UNICEF Indicator Data

Fetch UNICEF data for an indicator and one or more countries.

Returns annual observations from the UNICEF SDMX API. Use format="compact" (default) for a clean 5-column table; use format="full" for all columns including disaggregation details and confidence bounds.

indicator accepts BOTH codes AND human-readable names (v0.7.0). Pass whichever you have from the user's question — the server resolves names to canonical codes for you. Examples: indicator='CME_MRM0' → code passthrough indicator='neonatal mortality' → resolves to 'CME_MRM0' indicator='Under-five mortality rate' → resolves to 'CME_MRY0T4' indicator='U5MR' → resolves to 'CME_MRY0T4' indicator='stunting' → resolves to 'NT_ANT_HAZ_NE2' indicator='LBW' / 'low birth weight' → resolves to 'NT_BW_LBW' Acronyms accepted: NMR, IMR, U5MR, SBR, LBW, ANC1, SAB, BCG, DTP1/3 …

Genuinely ambiguous queries are refused with a disambiguation list. Examples: indicator='child mortality' → refused: pick CME_MRM0 / CME_MRY0 / CME_MRY0T4 / CME_MRY1T4 indicator='vaccination' → refused: pick IM_BCG / IM_DTP1/3 / IM_MCV1/2

Prefer passing the user's phrasing verbatim over guessing the code from memory — that's where the v0.6.x had a documented failure mode (model recalls CME_MRY0T4 thinking it's neonatal mortality; it's under-five). The response echoes the resolution under indicator_resolution so you can confirm the canonical code+name match the user's intent.

countries accepts BOTH ISO3 codes AND country names (v0.6.2). Pass whichever you have from the user's question — the server resolves country names to canonical ISO3 codes for you. Examples: countries=['Burundi'] → resolves to ['BDI'] countries=['BDI', 'Belgium'] → resolves to ['BDI', 'BEL'] countries=['Cote d'Ivoire'] → resolves to ['CIV'] countries=['USA', 'UK'] → resolves to ['USA', 'GBR'] Common synonyms accepted: 'USA'/'United States', 'UK'/'Great Britain', 'Ivory Coast'/'Cote d'Ivoire', 'South Korea', 'DRC', 'Czech Republic', 'Burma', 'Vatican', etc. The response echoes the resolution under country_resolutions and the canonical name+code pairs under countries_returned_with_names so you can confirm intent matched.

Prefer passing the user's country name verbatim over guessing the ISO3 code from memory — that's where v0.6.0 had a documented failure mode.

v0.6.0 server-side hardening: this tool also performs a pre-flight year-frontier check. If start_year or end_year exceeds the indicator's data frontier (max year observed), the call is refused server-side without issuing the SDMX request — preventing the silent-truncation pattern where a range like 2020-2027 returns 2020-2024 and the model extrapolates the missing years. Successful responses include a data_frontier field naming the max year and an explicit no-extrapolation directive.

Disaggregation filters (v1.2.0): sex: "_T" (total, default), "M" (male), "F" (female). age: SDMX AGE code such as "Y0T4", "Y15T19", "Y15T24". The age codelist depends on the indicator's dataflow — call get_indicator_info(code) to see what's supported. filters: dict[str, str | None] for every other dimension. Examples: filters={"WEALTH_QUINTILE": "Q1"} → poorest quintile filters={"RESIDENCE": "U"} → urban filters={"EDUCATION_LEVEL": "ISCED11_2"} → secondary filters={"WEALTH_QUINTILE": "Q1", "RESIDENCE": "U"} → both A None value is treated as "use the dim's total" (typically "_T").

When any non-_T filter is present (typed age= or filters dict non-empty), the response carries mode: "raw_filtered" to signal that the underlying call switched to raw=True + post-filter — same call, different number versus a totals-only response.

Validation: filters are checked against the indicator's actual primary dataflow before the SDMX call. Unsupported (dim, value) pairs are refused with a failed_validation envelope listing available dimensions and codelist values, so the LLM can recover in a single wave instead of retrying blindly.

BREAKING CHANGE FROM v1.1.x: the typed wealth_quintile= and residence= kwargs no longer route to the SDMX call — they are present in the signature only as deprecation trip-wires. Pass them and the call returns a structured migration error pointing at filters={"WEALTH_QUINTILE": ...}. v1.1.x silently dropped these kwargs at the SDMX call and returned the totals slice — that hazard is gone.

Limit defaults to 200 rows — narrow your country/year filters or increase limit (max 500) if you need more data. In raw_filtered mode, rows_truncated: true also means the pre-filter raw pull was larger than limit, so post-filter rows you wanted may be missing.