---
title: "Regional CPI and GDP API | Narwhal API"
description: "Read the latest CPI of a Malaysian state and the latest GDP of a Malaysian or US state by region code, with REST and MCP, the base, unit and release date stated."
url: "https://narwhalapi.com/docs/api/economics/regional"
---

# 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

| Parameter | In | Type | Required | Meaning |
| --- | --- | --- | --- | --- |
| `country` | path | string | Yes | An 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`. |
| `region` | path | string | Yes | An 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`. |
| `period` | query | string | No | Omit 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.

| Field | Type | Meaning |
| --- | --- | --- |
| `country` | string | The country code you asked for. |
| `region` | string | The region code you asked for. |
| `region_name` | string | The name of the region, such as `Selangor`. |
| `period` | string | The month the index is for, as `YYYY-MM`. |
| `value` | decimal string | The index level for the month. It is for all items. |
| `index_base` | string | The base of the index. It is `2010=100` for Malaysia. |
| `released_on` | date | The day the statistics office published the figure. |
| `source` | object | Present only when a distributor, not the original publisher, supplies the data. The Malaysian series do not carry it. |

### The GDP route returns these fields.

| Field | Type | Meaning |
| --- | --- | --- |
| `country` | string | The country code you asked for. |
| `region` | string | The region code you asked for. |
| `region_name` | string | The name of the region, such as `California`. |
| `period` | string | The year as `YYYY` for Malaysia, or the quarter as `YYYY-QN` for the United States. |
| `value` | decimal string | GDP in whole units of `currency`. Malaysian values are real, at constant prices of `base_period`. US values are at current prices. |
| `currency` | string | The ISO 4217 currency of `value`: `MYR` for Malaysia, `USD` for the United States. |
| `base_period` | string | The 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_adjusted` | true | Present, 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. |
| `annualized` | true | Present, 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_on` | date | The day the statistics office published the figure. |
| `source` | object | Present 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

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

### 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

| Region | Name |
| --- | --- |
| `US-AL` | Alabama |
| `US-AK` | Alaska |
| `US-AZ` | Arizona |
| `US-AR` | Arkansas |
| `US-CA` | California |
| `US-CO` | Colorado |
| `US-CT` | Connecticut |
| `US-DE` | Delaware |
| `US-DC` | District of Columbia |
| `US-FL` | Florida |
| `US-GA` | Georgia |
| `US-HI` | Hawaii |
| `US-ID` | Idaho |
| `US-IL` | Illinois |
| `US-IN` | Indiana |
| `US-IA` | Iowa |
| `US-KS` | Kansas |
| `US-KY` | Kentucky |
| `US-LA` | Louisiana |
| `US-ME` | Maine |
| `US-MD` | Maryland |
| `US-MA` | Massachusetts |
| `US-MI` | Michigan |
| `US-MN` | Minnesota |
| `US-MS` | Mississippi |
| `US-MO` | Missouri |
| `US-MT` | Montana |
| `US-NE` | Nebraska |
| `US-NV` | Nevada |
| `US-NH` | New Hampshire |
| `US-NJ` | New Jersey |
| `US-NM` | New Mexico |
| `US-NY` | New York |
| `US-NC` | North Carolina |
| `US-ND` | North Dakota |
| `US-OH` | Ohio |
| `US-OK` | Oklahoma |
| `US-OR` | Oregon |
| `US-PA` | Pennsylvania |
| `US-RI` | Rhode Island |
| `US-SC` | South Carolina |
| `US-SD` | South Dakota |
| `US-TN` | Tennessee |
| `US-TX` | Texas |
| `US-UT` | Utah |
| `US-VT` | Vermont |
| `US-VA` | Virginia |
| `US-WA` | Washington |
| `US-WV` | West Virginia |
| `US-WI` | Wisconsin |
| `US-WY` | Wyoming |

## 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](https://narwhalapi.com/docs/errors.md) · [Economics API reference](https://narwhalapi.com/docs/api/economics.md)

Was this page helpful?
