# Countries ## Tools Global development indicators — population, GDP, life expectancy, CO₂, and thousands more, for every country and year. Data from World Bank (CC BY 4.0). See [Countries](/docs/data/sources/countries) for coverage, freshness and credits. Your agent reaches these on Vistazo's MCP server, `https://mcp.vistazo.ai/mcp`, through `search_tools` and `call_tool`, as `countries__` — for example `countries__search_indicators`. | Tool | What it does | | |---|---|---| | [`search_indicators`](#search_indicators) | Search indicators | Read-only | | [`list_indicators`](#list_indicators) | List indicators | Read-only | | [`get_metadata`](#get_metadata) | Get indicator metadata | Read-only | | [`get_disaggregation`](#get_disaggregation) | Get disaggregation | Read-only | | [`find_codelist_value`](#find_codelist_value) | Find codelist value | Read-only | | [`expand_country_group`](#expand_country_group) | Expand country group | Read-only | | [`get_data`](#get_data) | Get indicator data | Read-only | | [`rank_countries`](#rank_countries) | Rank countries | Read-only | | [`compare_periods`](#compare_periods) | Compare periods | Read-only | ## search_indicators `Read-only` · `Reaches outside Vistazo` Search World Bank indicators by keyword (e.g. "GDP per capita", "life expectancy"). Returns `results`: matching indicators with their id, database_id, definition, and coverage — the entry point for every other tool. Optionally verify a country is covered. Sibling ids differ by unit suffix: _CD = current US$ (the headline figure), _KD = constant US$ (growth over time), _PP_CD = PPP international $ (living-standard comparisons), _CN/_KN = local currency — pick by what the chart compares. ## list_indicators `Read-only` · `Reaches outside Vistazo` List the indicator ids in a database, paginated in `indicators` (limit/offset, default 200 per page; the response carries the full count and has_more). Use search_indicators first to find the database_id — and prefer it for discovery, since large databases hold thousands of ids. ## get_metadata `Read-only` · `Reaches outside Vistazo` Fetch an indicator's full metadata — definition, methodology, source, limitations, and `aggregation_method` (how the source computes its regional/income aggregate rows, e.g. 'Weighted average' or 'Sum'). Use to understand exactly what a number measures before charting it, and before quoting an aggregate as a regional average. ## get_disaggregation `Read-only` · `Reaches outside Vistazo` List the dimensions available for an indicator, in `dimensions` — which years have data (TIME_PERIOD), how many countries (REF_AREA), and breakdowns like SEX/AGE. Call this before get_data to know valid years and filters. REF_AREA is summarized as a count plus a short sample; to check whether a specific country is present, pass `contains` (e.g. "italy") to search that codelist by code or name. ## find_codelist_value `Read-only` · `Reaches outside Vistazo` Translate a human name into the standardized code the API needs — e.g. "Kenya" → "KEN", "European Union" → "EUU", "female" → "F", "South America" → "M49_005". Returns ranked `matches` (preferring codes get_data actually accepts); use the top id. A match with dimension COUNTRY_GROUP is a UN M49 geographic subregion: expand it with expand_country_group, never pass it to get_data. ## expand_country_group `Read-only` · `Reaches outside Vistazo` Expand a group code into its member countries — a World Bank group, e.g. "SAS" (South Asia) or "LIC" (Low income), or a UN M49 geographic subregion, e.g. "M49_005" (South America) → `countries` [{code, name}] plus `country_codes`. The seven World Bank regions are EAS, ECS, LCN, MEA, NAC, SAS and SSF; the income groups LIC, LMC, UMC and HIC. Membership is the World Bank's own country list, so SAS holds six economies (no Afghanistan or Pakistan). Use to turn a group into countries for get_data, rank_countries or compare_periods. A subregion has no published aggregate rows; its members carry `status` "sovereign" or "territory", with `sovereign_codes` / `territory_codes` alongside. Pre-computed aggregates (e.g. "EUU", "WLD") can't be expanded but are flagged as usable directly. ## get_data `Read-only` · `Reaches outside Vistazo` Fetch the actual time-series observations for one indicator — or for up to 10 at once, by passing several ids in `indicator_id` separated by ";" or ",". Returns `rows`, one per indicator-country-year (indicator_id, ref_area, time_period, obs_value) — chart-ready, and a multi-indicator result feeds a multi-series chart from ONE call, which is how to build a themed dashboard instead of firing a call per indicator. Also returns the constant unit hoisted out of the rows (single-indicator form), `aggregate_codes` naming which returned areas are regional/income aggregates rather than countries, and `per_indicator` carrying each id's own count and coverage note. For particular years, pass `years` (e.g. [2013, 2023]) and omit `limit`: each comes back complete for every country, except that one response holds at most 1000 rows (12,000 for a notebook's call — vistazo.call or a data cell), so with several indicators each gets 1000 ÷ indicators (a full year is ~265 rows — three indicators for one year fit whole) and the response marks any it cut INCOMPLETE. Indicators × named years is capped at 20 upstream fetches per call. A wide span with a small `limit` keeps only the newest years, and the response names the ones it dropped. Breakdowns default to totals unless you filter. For the LATEST year per country, rank_countries with no `year` picks the most recent year with broad coverage and returns the year it used; here the newest rows come first. Call get_disaggregation first to learn valid years and filters. ## rank_countries `Read-only` · `Reaches outside Vistazo` Rank countries by an indicator value for a year — leaderboards and top/bottom lists. Rank the whole world, a group (via country_group like "SAS"), or an explicit set (country_codes). Returns `rankings` (not `rows`): rank, country, value, and percentile per entry, plus the database_id/indicator_id ranked and the values' unit (`unit_measure` code, `units` code → name; unit_measure is null when the values carry several units). Percentile is position WITHIN the ranked set — areas in the chosen universe with a value that year — so ranking two countries gives 100 and 50, not their world standing. ## compare_periods `Read-only` · `Reaches outside Vistazo` Rank countries by how much an indicator CHANGED between two years — "grew the most over the last decade", "fell furthest since 2010". One call returns `rows`: each country's start value, end value, absolute change and % change, sorted (sort_by change_pct | change | end_value | start_value) and capped by top_n. Do not assemble this from two get_data calls. Regional and income aggregates (EUU, WLD, IDA…) are excluded unless you ask for them, population rides along, and `min_population` keeps very small economies from dominating a percentage ranking. Both years are compared exactly — an area missing either one is excluded and counted, never silently shifted to a nearby year.