Any series API reference

Search the World Bank and Statistics Canada catalogues and read series by ID, with plan limits, caching and error handling.

Four operations give access to World Bank and Statistics Canada series by ID. Search the catalogue, read a series definition or its observations, or get the latest value for up to 50 series at once.

REST and MCP share schemas, a key and quota. Live World Bank and Statistics Canada series read by ID have no revision history. Pro keys can read vintages on supported country history and series-by-id routes, as described under Series history by ID in the Economics API reference.

Operations

Operation	REST path	MCP tool	Returns
Search the catalogue	`GET /v1/economics/catalogue`	`economics_search_catalogue`	Series and tables that match the query.
Read a series	`GET /v1/economics/catalogue/series`	`economics_read_catalogue_series`	One series definition.
Read observations	`GET /v1/economics/catalogue/series/observations`	`economics_read_catalogue_observations`	One series' values, oldest first.
Latest values	`GET /v1/economics/catalogue/latest`	`economics_read_catalogue_latest_batch`	The latest value for each of 1 to 50 series.

A source key can contain a slash, so pass the series ID in the id query parameter.

Every request needs a Bearer key. Authentication

Series IDs

Series IDs use the lowercase format <source>:<key>.

Source	Format	Example	Frequencies
World Bank, World Development Indicators	`wdi:<indicator>/<iso3>`	`wdi:ny.gdp.mktp.cd/idn`	Annual
Statistics Canada	`statcan:v<vector>`	`statcan:v41690973`	Monthly, quarterly, annual

World Bank search results have an id_template, such as wdi:ny.gdp.mktp.cd/{country}. Replace {country} with a lowercase ISO 3166-1 alpha-3 country code. The index includes only indicators published under CC BY 4.0; other indicators return 404 not_found.

Statistics Canada search results identify tables. Each result has the id_template statcan:v{vector} and a title with the table number, such as table 10-10-0106-01. Find the series' vector number on that table's Statistics Canada webpage and insert it into the template. No route currently lists a table's vectors.

Statistics Canada vectors with daily, weekly, multi-year, fiscal-year or fiscal-quarter frequencies return 404 not_found.

Search the catalogue

Search uses Narwhal's index without a source call. It is available on every plan and counts as one call.

q: search text, 2 to 100 characters.
source: wdi or statcan.
country: uppercase ISO alpha-3 code.
frequency: daily, monthly, quarterly or annual.
limit: 1 to 100; default 25.
cursor: next_cursor from the previous page.

Each result includes source, title and exactly one of id or id_template. It also includes frequency, unit_label, country, first_period and last_period when known. The last page has a next_cursor of null.

curl --request GET \
  --url "https://api.narwhalapi.com/v1/economics/catalogue?q=gdp&source=wdi&limit=2" \
  --header "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"
}

curl --request GET \
  --url "https://api.narwhalapi.com/v1/economics/catalogue?q=consumer%20price&source=statcan&limit=2" \
  --header "Authorization: Bearer $NARWHAL_API_KEY"

{
  "results": [
    {
      "id_template": "statcan:v{vector}",
      "source": "statcan",
      "title": "Consumer Price Index (CPI) statistics, alternative measures, unadjusted and seasonally adjusted, Bank of Canada (Statistics Canada table 10-10-0106-01)",
      "frequency": "monthly",
      "country": "CAN",
      "first_period": "1979-11",
      "last_period": "2026-09"
    },
    {
      "id_template": "statcan:v{vector}",
      "source": "statcan",
      "title": "Inter-city indexes of price differentials of consumer goods and services, annual (Statistics Canada table 18-10-0003-01)",
      "frequency": "annual",
      "country": "CAN",
      "first_period": "2000",
      "last_period": "2019"
    }
  ],
  "next_cursor": "eyJhIjoic3RhdGNhbjp0MTgxMDAwMDMiLCJxIjoiNGQxYjFkOWQwN2FlNTBhMiJ9"
}

Read a series

Returns one series definition, including its first and last periods. Observations are excluded.

curl --request GET \
  --url "https://api.narwhalapi.com/v1/economics/catalogue/series?id=wdi:ny.gdp.mktp.cd/idn" \
  --header "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",
  "attribution": "World Bank, World Development Indicators, CC BY 4.0. Values normalised by Narwhal.",
  "licence_url": "https://creativecommons.org/licenses/by/4.0/",
  "fetched_at": "2026-10-27T03:37:35Z",
  "first_period": "1967",
  "last_period": "2025"
}

curl --request GET \
  --url "https://api.narwhalapi.com/v1/economics/catalogue/series?id=statcan:v41690973" \
  --header "Authorization: Bearer $NARWHAL_API_KEY"

{
  "id": "statcan:v41690973",
  "title": "Canada;All-items",
  "frequency": "monthly",
  "unit": "extended",
  "unit_label": "2002=100",
  "seasonal_adjustment": "not_stated",
  "attribution": "Contains information licensed under the Open Government Licence - Canada. Source: Statistics Canada. Values normalised by Narwhal.",
  "licence_url": "https://open.canada.ca/en/open-government-licence-canada",
  "fetched_at": "2026-10-27T12:30:59Z",
  "first_period": "1914-01",
  "last_period": "2026-09"
}

Read observations

Returns one series' values in order from oldest to newest, together with its definition.

id: series ID.
start and end: inclusive bounds in the series' period format, YYYY, YYYY-MM or YYYY-Qn. Both bounds must use the same format.
limit: 1 to 1000; default 100.
cursor: next_cursor from the previous page.

Narwhal applies your plan's history window after start and end.

curl --request GET \
  --url "https://api.narwhalapi.com/v1/economics/catalogue/series/observations?id=wdi:ny.gdp.mktp.cd/idn&limit=3" \
  --header "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",
  "attribution": "World Bank, World Development Indicators, CC BY 4.0. Values normalised by Narwhal.",
  "licence_url": "https://creativecommons.org/licenses/by/4.0/",
  "fetched_at": "2026-10-27T03:37:35Z",
  "observations": [
    {
      "period": "1967",
      "value": "5667756627.92093"
    },
    {
      "period": "1968",
      "value": "7076465299.81141"
    },
    {
      "period": "1969",
      "value": "8337423312.88344"
    }
  ],
  "next_cursor": "eyJhIjoiMTk2OSIsInEiOiI2ZDM2OTAzMzcyMGJmYmU1In0"
}

curl --request GET \
  --url "https://api.narwhalapi.com/v1/economics/catalogue/series/observations?id=statcan:v41690973&start=2026-07&limit=3" \
  --header "Authorization: Bearer $NARWHAL_API_KEY"

{
  "id": "statcan:v41690973",
  "title": "Canada;All-items",
  "frequency": "monthly",
  "unit": "extended",
  "unit_label": "2002=100",
  "seasonal_adjustment": "not_stated",
  "attribution": "Contains information licensed under the Open Government Licence - Canada. Source: Statistics Canada. Values normalised by Narwhal.",
  "licence_url": "https://open.canada.ca/en/open-government-licence-canada",
  "fetched_at": "2026-10-27T12:30:59Z",
  "observations": [
    {
      "period": "2026-07",
      "value": "169.9",
      "released_on": "2026-08-17"
    },
    {
      "period": "2026-08",
      "value": "169.8",
      "released_on": "2026-09-14"
    },
    {
      "period": "2026-09",
      "value": "170.0",
      "released_on": "2026-10-19"
    }
  ],
  "next_cursor": null
}

Years or months without published source values are omitted and never filled. Each observation has period and value, a decimal string; released_on and status are included when the source supplies them.

Latest values in one request

Send 1 to 50 distinct IDs as a comma-separated ids list. The response returns each series' latest observation and definition. The missing list contains IDs the source does not recognise or that have no observation.

curl --request GET \
  --url "https://api.narwhalapi.com/v1/economics/catalogue/latest?ids=wdi:ny.gdp.mktp.cd/idn,statcan:v41690973" \
  --header "Authorization: Bearer $NARWHAL_API_KEY"

{
  "observations": [
    {
      "period": "2025",
      "value": "1445642584163.81",
      "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",
      "attribution": "World Bank, World Development Indicators, CC BY 4.0. Values normalised by Narwhal.",
      "licence_url": "https://creativecommons.org/licenses/by/4.0/",
      "fetched_at": "2026-10-27T03:37:35Z"
    },
    {
      "period": "2026-09",
      "value": "170.0",
      "released_on": "2026-10-19",
      "id": "statcan:v41690973",
      "title": "Canada;All-items",
      "frequency": "monthly",
      "unit": "extended",
      "unit_label": "2002=100",
      "seasonal_adjustment": "not_stated",
      "attribution": "Contains information licensed under the Open Government Licence - Canada. Source: Statistics Canada. Values normalised by Narwhal.",
      "licence_url": "https://open.canada.ca/en/open-government-licence-canada",
      "fetched_at": "2026-10-27T12:30:59Z"
    }
  ],
  "missing": []
}

The batch is charged in one step at one call per series returned.

Plan limits

All four operations are available on every plan. Each plan sets a daily limit on uncached source fetches and a history window.

Limit	Free	Basic	Pro
Uncached fetches per UTC day	10	100	1,000
History window	Last 12 months	Last 5 years	Full history

Every plan includes at least the latest 5 observations of an annual series and the latest 4 of a quarterly series, even if they fall outside its history window. Narwhal uses whichever includes more: the window or those latest observations.

A range wholly before your plan's window returns 403 plan_upgrade_required. For annual and quarterly series, Narwhal loads the series before this check so it can apply the minimum observation count.

Data is live with no delay.

Calls, caching and stale data

Each successful search, series, observations or single-series latest request counts as one call. Batches count as one call per series returned.

Stale responses and 400, 404 and 503 responses are uncharged.

Narwhal caches each series after a source read. A cached series always returns a response without a fetch; only an uncached series uses a fetch. World Bank series are cached for 24 hours to 7 days. Statistics Canada cache times are 6 hours for monthly series, 12 hours for quarterly series and 24 hours for annual series.

Once the account has used its daily fetches, a request that needs another returns 429 fetch_limit_reached. Its Retry-After header gives the time remaining until 00:00 UTC. If an older copy of the series is still available, Narwhal returns it with stale: true at no charge.

If the source is down and no copy is cached, Narwhal returns 503 upstream_busy with Retry-After. Source rate limits are never passed through as 429 responses.

Fields

Series responses include these fields.

Field	Meaning
`id`	Series ID.
`title`	Series title supplied by the source.
`country`	ISO alpha-3 code, when supplied by the source.
`frequency`	`daily`, `monthly`, `quarterly` or `annual`.
`unit`	Always `extended`.
`unit_label`	Unit in the source's own words. World Bank series use the indicator name, such as `GDP (current US$)`.
`scale, currency`	Included only when stated by the source. Narwhal never applies `scale` to values.
`seasonal_adjustment`	`seasonally_adjusted`, `not_seasonally_adjusted`, `not_applicable` or `not_stated`.
`base_period`	Index base, when stated by the source.
`attribution, licence_url`	Required source credit and a link to the source licence.
`fetched_at`	Time Narwhal read the source.
`stale`	`true` only when the source is unreachable and Narwhal returns the last copy it kept.
`first_period, last_period`	First and last periods, included in the series definition.

Errors

Status and code	Meaning
`400 invalid_series_id`	The ID has an invalid source format. The detail specifies `<indicator>/<iso3 country>` for World Bank or `v<vector number>` for Statistics Canada.
`400 invalid_query`	A parameter is invalid. Examples include more than 50 IDs in a batch, repeated IDs, or different period formats for `start` and `end`.
`403 plan_upgrade_required`	The requested range ends before your plan's history window.
`404 not_found`	The source or index does not recognise the series, or the series has an unsupported frequency. Narwhal caches this result for 24 hours.
`404 not_covered`	The ID names an unsupported source.
`429 fetch_limit_reached`	The account has used its fetch allowance for the UTC day. `Retry-After` gives the time remaining until 00:00 UTC.
`503 upstream_busy`	The source is unavailable and no copy is cached. Wait for the time specified by `Retry-After` before another attempt.

Errors have the shared problem shape and include a request_id. Errors and quota

World Bank data API · Statistics Canada data API

Attribution

Each response names the agency in attribution and links to its licence in licence_url. World Bank indicators use CC BY 4.0, and Statistics Canada data uses the Open Government Licence - Canada. Narwhal normalises the values; retain the source credit wherever you display them.

Economics API reference · MCP