---
title: "GDP growth API Reference | Narwhal API"
description: "Retrieve official real GDP growth for one quarter, measured at constant prices and expressed in percent. Parameters, examples, errors, freshness, and coverage."
url: "https://narwhalapi.com/docs/api/economics/gdp-growth"
---

# GDP growth API

Retrieve official real GDP growth for one quarter, measured at constant prices and expressed in percent.

`economics_get_gdp_growth` is available through REST and the `economics_get_gdp_growth` MCP tool. Both return the same data shape and use the same credit.

## Endpoint and request

REST endpoint

```
GET /v1/economics/{country}/gdp-growth
```

Example request

```
curl --request GET \
  --url "https://api.narwhalapi.com/v1/economics/USA/gdp-growth?period=2026-Q2" \
  --header "Authorization: Bearer $NARWHAL_API_KEY"
```

MCP uses tool `economics_get_gdp_growth` with the corresponding arguments below.

## Parameters

The accepted period format for this operation is `YYYY-QN`.

| Name | Required | Type | Meaning |
| --- | --- | --- | --- |
| `country` | Yes | path · ISO alpha-3 | One supported uppercase country code; see this operation’s coverage list. |
| `period` | No | query · YYYY-QN | Omit it for the latest accepted complete release, or pass one exact period. |
| `version_id` | No | query · UUID | Optional immutable publication version. Use `resource_version` from a `dataset.published` or `dataset.revised` event; omit to read the current admitted indicator. |

## Response

Example response

```
{
  "country": "USA",
  "period": "2026-Q2",
  "year_over_year": "2.2",
  "quarter_over_quarter": "0.6",
  "released_on": "2026-10-29",
  "calculated": [
    "quarter_over_quarter"
  ]
}
```

| Field | Type | Required | Meaning |
| --- | --- | --- | --- |
| `country` | string | Yes | The requested uppercase ISO alpha-3 country code. |
| `period` | string | Yes | The official observation period returned. |
| `year_over_year` | decimal string | Yes | Real GDP change from the same quarter one year earlier, in percent. |
| `quarter_over_quarter` | decimal string | No | Real GDP change from the previous quarter, in percent, not annualized. Left out where the publisher releases only the year-over-year figure, and for a yearly period. |
| `year_to_date` | decimal string | No | Official year-to-date growth, in percent, when the source publishes it; otherwise omitted. |
| `seasonal_adjustment` | string or null | Yes | Whether the figure is seasonally adjusted, as the publisher states it: `seasonally_adjusted`, `not_seasonally_adjusted`, `calendar_adjusted` or `trend`. `null` means the publisher does not say. Never read `null` as adjusted. `mixed` means the two growth figures are on different bases. Japan is one example: its year on year growth is not adjusted, and its quarter on quarter growth is. |
| `year_over_year_seasonal_adjustment` | string or null | Yes | The basis of each growth figure on its own, using the same values. They are filled only when `seasonal_adjustment` is `mixed`. Otherwise, or where the release does not state that figure's basis, they are `null`. |
| `quarter_over_quarter_seasonal_adjustment` | string or null | Yes | The basis of each growth figure on its own, using the same values. They are filled only when `seasonal_adjustment` is `mixed`. Otherwise, or where the release does not state that figure's basis, they are `null`. |
| `annualization` | string or null | Yes | Whether quarter on quarter growth is annualized: `annualized` or `not_annualized`. It is `null` when the answer has no quarter on quarter figure. Year on year growth is never annualized. |
| `not_seasonally_adjusted` | `true` | No | Present, as true, only when the growth rates are not seasonally adjusted. |
| `annualized` | `true` | No | Present, as true, only when the published growth rate is annualized. |
| `year_over_year_not_seasonally_adjusted` | `true` | No | Present, as true, only for a country that mixes bases: its year-over-year figure is not seasonally adjusted. The top-level flag is then absent. |
| `quarter_over_quarter_not_seasonally_adjusted` | `true` | No | Present, as true, only for a country that mixes bases: its quarter-over-quarter figure is not seasonally adjusted. The top-level flag is then absent. |
| `seasonally_adjusted` | `true` | No | Present, as true, only when both figures are recorded as seasonally adjusted. |
| `year_over_year_seasonally_adjusted` | `true` | No | Present, as true, only for a country that mixes bases: its year-over-year figure is seasonally adjusted. The top-level flag is then absent. |
| `quarter_over_quarter_seasonally_adjusted` | `true` | No | Present, as true, only for a country that mixes bases: its quarter-over-quarter figure is seasonally adjusted. The top-level flag is then absent. |
| `released_on` | date | Yes | The official publication date, not Narwhal's retrieval time. |
| `source` | object | No | Who published the figure: the statistics office or central bank, for example `{"publisher": "Office for National Statistics"}`. Where the data reaches us through another body, `distributor` names that body too. If we cannot tell who published a figure, `source` is left out. On a newest figure read from the publisher's own release, `source` is `{"publisher": "..."}` with no distributor, and `released_on` is the publisher's local release day. |
| `stage` | string | No | Appears only on a newest figure read from the publisher's release. Which reading of the figure this is: `flash`, `advance`, `first`, `second`, `third`, `preliminary` or `final`. |
| `published_at` | RFC 3339 timestamp | No | Appears only on a newest figure read from the publisher's release. When the publisher released the figure. |
| `provisional` | `true` | No | Present, as true, only when the figure read from the release is marked provisional. |
| `calculated` | array of strings | No | Present only when Narwhal calculated a figure from the publisher's own numbers because the publisher does not print it. Lists the calculated figures: `["year_over_year"]`, `["quarter_over_quarter"]` or both. A printed figure always wins over a calculated one. A stored answer can carry it too, not only an answer read from the release. |

### Newest figure read from the release

The newest answer can come from Narwhal's own read of the statistics office's release, before the stored series has it. Such an answer adds `source`, `stage`, `published_at` and `provisional` (only when true). An answer with none of these fields is the stored value. A stored answer can also carry `calculated`, which lists the figures Narwhal calculated from the publisher's own numbers.

For a country with a stored series, a read value is shown when it is for a later period than the stored one, or a later final reading of the same period.

Where a stored series reaches Narwhal through a distributor, the statistics office's own printed figure for the same period replaces it. The answer then names the office as the source and no distributor.

It also answers the newest figure for a country that has no stored series, from the release alone, with the same fields and the same charge: Cameroon, Chad, Comoros, Cyprus, Fiji, Guadeloupe, Hong Kong, Hungary, Iceland, Martinique, Morocco, New Caledonia, Niger, Papua New Guinea, Senegal and Taiwan. It has no history: a `period` or `version_id` request for such a country returns `404 series_not_found`.

For these countries GDP growth is answered only when the office's release or its own tables state whether each figure is seasonally adjusted. A year-over-year figure whose basis is not stated is a `404 series_not_found`, and a quarter-over-quarter figure whose basis is not stated, or that is annualised, is left out of the answer.

Example request

```
curl --request GET \
  --url "https://api.narwhalapi.com/v1/economics/SEN/gdp-growth" \
  --header "Authorization: Bearer $NARWHAL_API_KEY"
```

Example response

```
{
  "country": "SEN",
  "period": "2026-Q2",
  "year_over_year": "6.1",
  "quarter_over_quarter": "0.1",
  "released_on": "2026-10-02",
  "source": {
    "publisher": "Agence Nationale de la Statistique et de la Démographie"
  },
  "stage": "preliminary",
  "published_at": "2026-10-02T10:00:00Z"
}
```

Example request

```
curl --request GET \
  --url "https://api.narwhalapi.com/v1/economics/GBR/gdp-growth" \
  --header "Authorization: Bearer $NARWHAL_API_KEY"
```

Example response

```
{
  "country": "GBR",
  "period": "2026-Q3",
  "year_over_year": "1.9",
  "quarter_over_quarter": "0.7",
  "released_on": "2026-11-12",
  "source": {
    "publisher": "Office for National Statistics"
  },
  "stage": "preliminary",
  "published_at": "2026-11-12T07:00:00Z"
}
```

## Errors and credits

- `400 invalid_query` — the country, period, or filter format is invalid.
- `401 invalid_api_key` — the Bearer key is missing or rejected.
- `404 series_not_found` — no approved observation matches the request.
- `429 rate_limit_exceeded` — the network or account short-window limit was reached; retry after `Retry-After`.
- `402 insufficient_credits` — your balance does not cover the call.
- `503 economics_unavailable` — Narwhal cannot safely serve an accepted publication.

Only a successful data response costs credit. See [all errors, headers, and retry rules](https://narwhalapi.com/docs/errors.md).

## Freshness

Omitting `period` returns Narwhal's latest stored accepted release. The API call reads Narwhal's database; it does not call the official publisher live.

`released_on` is the official publication date.

The newest figure can be shown as soon as the publisher releases it, from Narwhal's read of the release. Until the stored series has the same period, the answer carries the read fields described above.

Read [how source checks, validation, stored releases, and failed checks work](https://narwhalapi.com/docs/freshness.md).

## Current public-beta coverage

36 Countries

`AUS, AUT, BEL, CAN, CHL, COL, CZE, DEU, DNK, ESP, EST, FIN, FRA, GBR, HRV, IRL, ITA, JPN, LTU, LUX, LVA, MEX, MYS, NLD, NOR, NZL, PAK, PHL, POL, PRT, QAT, SAU, SGP, SVN, SWE, USA`

Quarterly year-over-year and quarter-over-quarter growth follow the country list below. The optional year_to_date field appears only when the official source publishes it.

### Annual World Bank history

165 Countries

`ABW, AFG, AGO, ALB, AND, ARE, ARM, ASM, ATG, AZE, BDI, BEN, BFA, BGR, BHR, BHS, BIH, BLR, BLZ, BMU, BOL, BRB, BRN, BTN, BWA, CAF, CIV, CMR, COD, COG, COM, CPV, CRI, CUB, CUW, CYM, CYP, DJI, DMA, DOM, DZA, ECU, EGY, ERI, ETH, FJI, FRO, FSM, GAB, GEO, GHA, GIN, GMB, GNB, GNQ, GRC, GRD, GRL, GTM, GUM, GUY, HKG, HND, HTI, HUN, IMN, IRN, IRQ, ISL, JAM, JOR, KAZ, KEN, KGZ, KHM, KIR, KNA, KWT, LAO, LBN, LBR, LBY, LCA, LIE, LKA, LSO, MAC, MAF, MAR, MCO, MDA, MDG, MDV, MHL, MKD, MLI, MLT, MMR, MNE, MNG, MNP, MOZ, MRT, MUS, MWI, NAM, NCL, NER, NGA, NIC, NPL, NRU, OMN, PAN, PER, PLW, PNG, PRI, PRY, PSE, PYF, ROU, RUS, RWA, SDN, SEN, SLB, SLE, SLV, SMR, SOM, SRB, SSD, STP, SUR, SVK, SWZ, SXM, SYC, SYR, TCA, TCD, TGO, TJK, TKM, TLS, TON, TTO, TUN, TUR, TUV, TZA, UGA, UKR, URY, UZB, VCT, VEN, VIR, VNM, VUT, WSM, YEM, ZMB, ZWE`

These countries have no latest-value route. A request to this route returns `404 series_not_found`; read the history route instead.

Indonesia and regional Economics routes are not public. Daily FX is available through the [FX API](https://narwhalapi.com/api/fx.md).

Return to [all Economics operations](https://narwhalapi.com/docs/api/economics.md).

## Start with a free key

Free $10 credits every month, no card.Free $10 credits a month, no card.

[Get a free API key](https://narwhalapi.com/signup)

Was this page helpful?
