World Bank Data API

Read annual indicators by country

Read a WDI indicator for a country with wdi:<indicator>/<iso3>, subject to the licence restrictions below. Both parts use lowercase letters. The country part is an ISO 3166-1 alpha-3 code, such as idn for Indonesia.

WDI series are annual. Responses preserve the indicator's unit label, and observation values are decimal strings. Missing years are dropped, never filled. A series has no revision history or vintages.

Search for an indicator

Search the catalogue with q and restrict results to source=wdi. Search is open on every plan and makes no request to the source. Queries accept 2 to 100 characters; limit accepts 1 to 100 results and defaults to 25.

curl "https://api.narwhalapi.com/v1/economics/catalogue?q=gdp&source=wdi&limit=2" \
  -H "Authorization: Bearer $NARWHAL_API_KEY"

{
  "results": [
    {
      "id_template": "wdi:bg.gsr.nfsv.gd.zs/{country}",
      "source": "wdi",
      "title": "Trade in services (% of GDP)",
      "frequency": "annual",
      "unit_label": "Trade in services (% of GDP)"
    },
    {
      "id_template": "wdi:bm.klt.dinv.wd.gd.zs/{country}",
      "source": "wdi",
      "title": "Foreign direct investment, net outflows (% of GDP)",
      "frequency": "annual",
      "unit_label": "Foreign direct investment, net outflows (% of GDP)"
    }
  ],
  "next_cursor": "eyJhIjoid2RpOmJtLmtsdC5kaW52LndkLmdkLnpzIiwicSI6IjBhOTNhNWZiMmE1NzkzY2EifQ"
}

Replace {country} in a result's id_template with your country code. The corresponding MCP tool is economics_search_catalogue.

Read the series

Pass the complete ID in the id query parameter, including its slash. Read the definition first to check the title, frequency and unit label. For Indonesia's GDP, the source's unit label is GDP (current US$).

curl "https://api.narwhalapi.com/v1/economics/catalogue/series?id=wdi:ny.gdp.mktp.cd/idn" \
  -H "Authorization: Bearer $NARWHAL_API_KEY"

{
  "id": "wdi:ny.gdp.mktp.cd/idn",
  "title": "GDP (current US$), Indonesia",
  "country": "IDN",
  "frequency": "annual",
  "unit": "extended",
  "unit_label": "GDP (current US$)",
  "seasonal_adjustment": "not_stated",
  "first_period": "1967",
  "last_period": "2025"
}

Read observations separately. Annual start and end bounds use YYYY and are inclusive. Observation pages accept up to 1,000 records. In MCP, use economics_read_catalogue_series for the definition and economics_read_catalogue_observations for values.

curl "https://api.narwhalapi.com/v1/economics/catalogue/series/observations?id=wdi:ny.gdp.mktp.cd/idn&limit=3" \
  -H "Authorization: Bearer $NARWHAL_API_KEY"

{
  "id": "wdi:ny.gdp.mktp.cd/idn",
  "observations": [
    {"period": "1967", "value": "5667756627.92093"},
    {"period": "1968", "value": "7076465299.81141"},
    {"period": "1969", "value": "8337423312.88344"}
  ],
  "next_cursor": "eyJhIjoiMTk2OSIsInEiOiI2ZDM2OTAzMzcyMGJmYmU1In0"
}

Read many countries at once

Send 1 to 50 distinct series IDs in a comma-separated ids parameter to read their latest observations. Keep the indicator part fixed and change the country code to request the same indicator across countries.

curl "https://api.narwhalapi.com/v1/economics/catalogue/latest?ids=wdi:ny.gdp.mktp.cd/idn,wdi:ny.gdp.mktp.cd/jpn" \
  -H "Authorization: Bearer $NARWHAL_API_KEY"

Each returned series costs one call, and the batch is charged in one step. Check each observation's period when comparing values. The MCP tool is economics_read_catalogue_latest_batch.

Check limits by plan

Uncached fetch allowances apply per account per UTC day. A fetch is needed only when a series is absent from the cache; cached series remain readable after the daily allowance is used.

Annual access includes the plan window or the latest 5 observations, whichever includes more. A range wholly before the permitted history returns 403 plan_upgrade_required.

When a request needs a fetch after the allowance is exhausted, it returns 429 fetch_limit_reached with Retry-After to 00:00 UTC. An account at its cap with a kept copy receives that copy uncharged.

Keep the licence and attribution

The catalogue indexes 1,489 World Bank WDI indicators under CC BY 4.0. Nine indicators with other licences are refused by ID and are not served.

Every series response includes attribution and licence_url. Keep the World Bank attribution and CC BY 4.0 licence with the data you use. The response also carries fetched_at, so you can record when Narwhal retrieved the series alongside its observation periods.

How do I get a World Bank indicator by country code?

Search for the indicator, take its id_template, and replace {country} with a lowercase ISO 3166-1 alpha-3 code. For example, Indonesia's GDP series is wdi:ny.gdp.mktp.cd/idn.

Pass that full ID as the id parameter when reading the definition or observations. Keep the country code attached to the indicator when storing or comparing series.

How current is the World Bank data?

WDI observations are annual, and Narwhal caches series for 24 hours to 7 days. On a cache miss, Narwhal fetches from the source within your plan's daily allowance.

Check the observation's period separately from fetched_at: one identifies the year measured, while the other records retrieval time. If the source is unreachable, a kept copy can be returned with stale: true.