Get World Bank Indicator Data
worldbank_get_dataRead-onlyIdempotent
Query World Bank indicator values for one or more countries across a time range — the primary data-access tool; find indicator_id values with worldbank_search_indicators. Observations carry a null value where data is not available for a country×year cell, which is common for sparse series. Set at most one of date_range (a time window), mrv (the latest N periods across the requested countries), or mrnev (each country's own latest N values). Some series, such as Global Economic Monitor's, publish quarterly or monthly values beside annual ones: frequency picks the form mrv and mrnev select from (annual by default), and a date_range's own form (2024, 2024Q1, 2024M01) picks it for a window. lastUpdated gives the serving source's last update date, the data vintage to cite. For "all" countries, page through the results at up to 1000 per page, since the API returns several hundred entries per indicator. Indicators the standard data endpoint does not serve — WDI Database Archives, PEFA, ICP, GDLD, International Debt Statistics: DSSI, Food Prices for Nutrition — are answered from their own dataset instead; the response then carries sourceScoped, naming that dataset and the release, classification, sector, or counterpart area applied (see dimension_value), because those values can be archived or superseded figures rather than current ones.
Input Schema
| Name | Required | Description | Default |
|---|---|---|---|
| mrv | No | Return the N most recent periods (1–100) holding a value for any requested country, clamped to the length of the series. Every requested country comes back at those periods, null where it has no value there rather than with its own older values; mrnev returns each country's own latest values instead. The periods are annual unless frequency names another form (a series with no annual periods keeps its own). Rows are mrv × countries, so page through them with per_page. Mutually exclusive with date_range and mrnev. | |
| page | No | Pagination page number (1-based). | |
| mrnev | No | Return each requested country's own N most recent periods (1–100) holding a value — its latest non-null observations, however far back they sit. A country with fewer values in the series returns the ones it has, and a country with none returns no rows. The periods are annual unless frequency names another form (a series with no annual periods keeps its own). Mutually exclusive with date_range and mrv. | |
| per_page | No | Results per page (default: server default). Positive integers above 1000 are served at that maximum with the requested and served sizes echoed and a notice. totalPages uses the served size. | |
| countries | Yes | Country codes. Accepts: ISO2 (US, CN), ISO3 (USA, CHN), regional aggregate codes (EAS, LCN, MEA, SAS, SSF, ECS, NAC), income group codes (HIC, UMC, LMC, LIC), world code (WLD), or "all" on its own for every entry (use pagination). Pass a single code, an array, or one string separated by commas, semicolons, or pipes (US,JP · US;JP · US|JP). At least one code is required — an empty value, or one made only of separators, is rejected rather than treated as "all". | |
| frequency | No | The period form to return, for series such as Global Economic Monitor's that publish quarterly or monthly values beside annual ones: annual (the default), quarterly, or monthly. With mrv or mrnev it picks the form they select from — frequency "monthly" with mrv 3 returns the three latest months, where mrv 3 alone returns the three latest years. With neither, it returns the whole series at that form. A series that does not publish the form returns an empty result with a notice saying so, except that with neither mrv nor mrnev a source that null-fills the form (Global Economic Monitor) returns null rows, and a page of them carries a notice. Mutually exclusive with date_range, whose own form (2024, 2024Q1, 2024M01) picks the periods of a window. | |
| source_id | No | Select this source dataset explicitly, including subnational sources. Use worldbank_list_countries with the same source_id for its canonical entity IDs. Omission preserves the standard dataset and automatic fallback. | |
| date_range | No | Time window to filter observations to. Accepts a whole year (`2020`), a quarter (`2020Q1`), or a month (`2020M03`), or a range of two periods of the same type separated by a colon, earliest first (`2010:2023`, `2020Q1:2021Q4`, `2020M01:2020M06`); a range running latest first is rejected. On a series publishing more than one period form, the window's form picks which: `2024` returns the annual value, `2024Q1:2024Q4` the quarters, `2024M01:2024M12` the months, and a quarter or month window is null-filled where the series has none (a notice then names the other forms). On a series with one form, a window at another form keeps the periods it overlaps (`2019:2021` on a quarterly series returns its twelve quarters). A window covering no part of the series returns zero observations rather than the full series. Mutually exclusive with mrv, mrnev, and frequency. | |
| indicator_id | Yes | One indicator code to query (e.g. NY.GDP.PCAP.CD, SP.POP.TOTL) — not "all" or a list of codes. Use worldbank_search_indicators to find valid IDs. | |
| dimension_value | No | For indicators answered from their own dataset (the response carries sourceScoped), the id of the value of that dataset's extra dimension to query, matched case-insensitively: a WDI Database Archives release ("202503"), an ICP or Food Prices for Nutrition classification ("PPPGlob", "FPN 5.0"), a GDLD sector ("WHT"), or an International Debt Statistics counterpart area ("265"). Omit it for the default, which sourceScoped.dimension reports: the only value when the dataset has one, "WLD" (World) for counterpart areas, the newest WDI Database Archives release holding data for the requested countries and periods (the newest release when none does), or otherwise every value with each row labelled. A value the dataset does not list is rejected with the valid ids, and a value for an indicator the standard data endpoint serves is rejected too. |
Output Schema
| Name | Required | Description | Default |
|---|---|---|---|
| data | No | Indicator observations for this page. Null values are common for sparse series. | |
| error | No | Present when the call failed. Absent on success. | |
| notice | No | Recovery hint for an empty result set — how to broaden the query when nothing matched, whether the series publishes the requested frequency, or the page range that exists when the requested page is past the end — a quarter or month date_range whose observations are all null, with the same span at the other period forms, a frequency page whose observations are all null, a page size reduced to the page cap, and, for source-scoped data, the requested country codes the serving dataset publishes nothing for. | |
| sourceId | No | Serving source ID, present only when established by the selected source or upstream response. | |
| indicator | No | Indicator metadata echoed from the response. | |
| nullCount | No | Count of null values on this page — indicates data sparsity for the requested filter. | |
| totalCount | No | Total observations before pagination. | |
| totalPages | No | Total number of pages. | |
| currentPage | No | Page number requested — past totalPages when the request ran off the end. | |
| lastUpdated | No | Last update date of the World Bank source that served these values (YYYY-MM-DD) — the data vintage to cite with them. Omitted when upstream reports none, as for an empty result. | |
| sourceScoped | No | Present when the source-scoped data API served the explicitly selected source or an automatic fallback dataset. | |
| appliedFilters | No | The effective parameters sent to the World Bank API — confirms country code normalization and which filters were in force for these observations. |