Browse all documentation

Regional economics API reference

Read the latest consumer price index and GDP of one Malaysian state or federal territory, and the latest GDP of one US state or DC, by region code.

Overview

Two routes return the latest figure for one region of a country. GET /v1/economics/{country}/regions/{region}/cpi returns the consumer price index of a Malaysian state or federal territory. GET /v1/economics/{country}/regions/{region}/gdp returns the GDP of a Malaysian state or federal territory, or of a US state or the District of Columbia. A region is an ISO 3166-2 code, such as MY-10 (Selangor) or US-CA (California).

The MCP tools are economics_get_regional_cpi and economics_get_regional_gdp. They take the same parameters as the routes and return the same fields.

Only the latest period is served. There is no history route and no route that lists regions. The region ids are on this page.

Requests

The consumer price index of Selangor, and its real response:

curl --request GET \
  --url "https://api.narwhalapi.com/v1/economics/MYS/regions/MY-10/cpi" \
  --header "Authorization: Bearer $NARWHAL_API_KEY"
Malaysia, Selangor, consumer price index
{
  "country": "MYS",
  "period": "2026-10",
  "value": "144.7",
  "index_base": "2010=100",
  "released_on": "2026-11-19",
  "region": "MY-10",
  "region_name": "Selangor"
}

The GDP of Selangor. Malaysian GDP is yearly, at constant 2015 prices, in ringgit:

curl --request GET \
  --url "https://api.narwhalapi.com/v1/economics/MYS/regions/MY-10/gdp" \
  --header "Authorization: Bearer $NARWHAL_API_KEY"
Malaysia, Selangor, GDP
{
  "not_seasonally_adjusted": true,
  "country": "MYS",
  "region": "MY-10",
  "region_name": "Selangor",
  "period": "2025",
  "value": "460113648000",
  "currency": "MYR",
  "base_period": "2015",
  "released_on": "2026-07-01"
}

The GDP of California. US state GDP is quarterly, at current prices, seasonally adjusted at annual rates, in US dollars:

curl --request GET \
  --url "https://api.narwhalapi.com/v1/economics/USA/regions/US-CA/gdp" \
  --header "Authorization: Bearer $NARWHAL_API_KEY"
United States, California, GDP
{
  "annualized": true,
  "country": "USA",
  "region": "US-CA",
  "region_name": "California",
  "period": "2026-Q2",
  "value": "4530521400000",
  "currency": "USD",
  "released_on": "2026-09-30"
}

Each response is one object. Values are decimal strings in whole units of the currency, so 4530521400000 is 4.53 trillion US dollars.

Parameters

ParameterInTypeRequiredMeaning
countrypathstringYesAn uppercase ISO 3166-1 alpha-3 country code. MYS for CPI and GDP, USA for GDP only. Any other country is 404 series_not_found.
regionpathstringYesAn uppercase ISO 3166-2 code of a region of country, such as MY-10 or US-CA. The ids are listed under Coverage and regions. A region of another country is 400 invalid_query.
periodquerystringNoOmit it for the latest period. The CPI route takes YYYY-MM. The GDP route takes YYYY for Malaysia and YYYY-QN for the United States, such as 2026-Q2. Only the latest period is served today, so any other period is 404 series_not_found.

Response

Both routes return a single object. A field that has no value is left out.

The CPI route returns these fields.

FieldTypeMeaning
countrystringThe country code you asked for.
regionstringThe region code you asked for.
region_namestringThe name of the region, such as Selangor.
periodstringThe month the index is for, as YYYY-MM.
valuedecimal stringThe index level for the month. It is for all items.
index_basestringThe base of the index. It is 2010=100 for Malaysia.
released_ondateThe day the statistics office published the figure.
sourceobjectPresent only when a distributor, not the original publisher, supplies the data. The Malaysian series do not carry it.

The GDP route returns these fields.

FieldTypeMeaning
countrystringThe country code you asked for.
regionstringThe region code you asked for.
region_namestringThe name of the region, such as California.
periodstringThe year as YYYY for Malaysia, or the quarter as YYYY-QN for the United States.
valuedecimal stringGDP in whole units of currency. Malaysian values are real, at constant prices of base_period. US values are at current prices.
currencystringThe ISO 4217 currency of value: MYR for Malaysia, USD for the United States.
base_periodstringThe base year of the constant prices, as YYYY. It is 2015 for Malaysia. It is left out for US values, which are at current prices.
not_seasonally_adjustedtruePresent, as true, only when the figure is not seasonally adjusted. Malaysian state GDP is yearly and carries it. A US figure without it is seasonally adjusted.
annualizedtruePresent, as true, only when the figure is stated at an annual rate. US state GDP carries it: the quarter's output at an annual rate, not the output of the quarter.
released_ondateThe day the statistics office published the figure.
sourceobjectPresent only when a distributor, not the original publisher, supplies the data. These series do not carry it.

Coverage and regions

Two countries are served. Every other country answers 404 series_not_found, and a region that does not belong to the country in the path answers 400 invalid_query.

Malaysia: 16 regions, CPI and GDP

The Department of Statistics Malaysia (DOSM) publishes both series for the 13 states and 3 federal territories. CPI is monthly, with the base 2010=100. GDP is yearly, real, at constant 2015 prices, in ringgit, for all economic sectors together. MY-16 (Putrajaya) has a CPI but no GDP of its own: DOSM counts it inside Kuala Lumpur (MY-14), so the GDP route answers 404 series_not_found for it.

Malaysian regions · 16
RegionName
MY-01Johor
MY-02Kedah
MY-03Kelantan
MY-04Melaka
MY-05Negeri Sembilan
MY-06Pahang
MY-07Pulau Pinang
MY-08Perak
MY-09Perlis
MY-10Selangor
MY-11Terengganu
MY-12Sabah
MY-13Sarawak
MY-14Kuala Lumpur
MY-15Labuan
MY-16Putrajaya

United States: 51 regions, GDP only

The US Bureau of Economic Analysis (BEA) publishes quarterly GDP for the 50 states and the District of Columbia, in current US dollars, seasonally adjusted at annual rates. The United States has no regional CPI here, so the CPI route answers 404 series_not_found for every US region.

US regions · 51
RegionName
US-ALAlabama
US-AKAlaska
US-AZArizona
US-ARArkansas
US-CACalifornia
US-COColorado
US-CTConnecticut
US-DEDelaware
US-DCDistrict of Columbia
US-FLFlorida
US-GAGeorgia
US-HIHawaii
US-IDIdaho
US-ILIllinois
US-INIndiana
US-IAIowa
US-KSKansas
US-KYKentucky
US-LALouisiana
US-MEMaine
US-MDMaryland
US-MAMassachusetts
US-MIMichigan
US-MNMinnesota
US-MSMississippi
US-MOMissouri
US-MTMontana
US-NENebraska
US-NVNevada
US-NHNew Hampshire
US-NJNew Jersey
US-NMNew Mexico
US-NYNew York
US-NCNorth Carolina
US-NDNorth Dakota
US-OHOhio
US-OKOklahoma
US-OROregon
US-PAPennsylvania
US-RIRhode Island
US-SCSouth Carolina
US-SDSouth Dakota
US-TNTennessee
US-TXTexas
US-UTUtah
US-VTVermont
US-VAVirginia
US-WAWashington
US-WVWest Virginia
US-WIWisconsin
US-WYWyoming

Freshness

  • The route reads Narwhal's database. It does not call the statistics office when you ask.
  • released_on is the day the office published the figure, not the day Narwhal stored it.
  • Narwhal checks the DOSM consumer price file daily, and the DOSM GDP file and the BEA state table weekly. A new month, year or quarter appears after the check that finds it.
  • Only the newest stored period answers. When a new one arrives, the older one is no longer served and a request for it is 404 series_not_found.

Price

Each successful call is one Economics call, $2 per 1,000 calls. A failed call costs nothing. REST and MCP use the same credit balance.

Errors

Errors use the problem format described in Errors and credits. These are the ones these routes return.

  • 400 invalid_query The country is not an uppercase alpha-3 code, the region is not an ISO 3166-2 code, the period has the wrong format, or the region does not belong to the country.
  • 401 invalid_api_key The Bearer key is missing or rejected.
  • 402 insufficient_credits Your balance does not cover the call.
  • 403 plan_upgrade_required The period is earlier than the history your plan includes. Upgrade for longer history.
  • 404 series_not_found No stored figure matches: a country with no regional series, a region that has none (MY-16 for GDP, any US region for CPI), or a period that is not the latest.
  • 429 rate_limit_exceeded The account or network short-window limit was reached. Retry after Retry-After.
  • 503 economics_unavailable Narwhal cannot safely serve the stored figure.
A region of another country (400)
curl --request GET \
  --url "https://api.narwhalapi.com/v1/economics/MYS/regions/US-CA/cpi" \
  --header "Authorization: Bearer $NARWHAL_API_KEY"
{
  "type": "https://narwhalapi.com/problems/invalid-query",
  "title": "Invalid query",
  "status": 400,
  "detail": "The request parameters are not valid for this operation.",
  "code": "invalid_query",
  "request_id": "a92025a3-00df-43c5-bb14-a31d6219074b"
}
A US region has no CPI (404)
curl --request GET \
  --url "https://api.narwhalapi.com/v1/economics/USA/regions/US-CA/cpi" \
  --header "Authorization: Bearer $NARWHAL_API_KEY"
{
  "type": "https://narwhalapi.com/problems/series-not-found",
  "title": "Economics series not found",
  "status": 404,
  "detail": "No complete approved economics publication matched the request.",
  "code": "series_not_found",
  "request_id": "02ad5496-cac3-46b7-9298-42f5b8bc29a9"
}
Putrajaya has no GDP of its own (404)
curl --request GET \
  --url "https://api.narwhalapi.com/v1/economics/MYS/regions/MY-16/gdp" \
  --header "Authorization: Bearer $NARWHAL_API_KEY"
{
  "type": "https://narwhalapi.com/problems/series-not-found",
  "title": "Regional GDP not published separately",
  "status": 404,
  "detail": "DOSM counts the GDP of this territory inside Wilayah Persekutuan Kuala Lumpur (MY-14), so no separate figure is served.",
  "code": "series_not_found",
  "request_id": "6edfc0f8-68f3-4732-b45b-a228be5d175b"
}

Errors and credits · Economics API reference

Was this page helpful?