---
title: "Unemployment API Reference | Narwhal API"
description: "Retrieve the official unemployment rate for one observation period. Parameters, examples, errors, freshness, and coverage."
url: "https://narwhalapi.com/docs/api/economics/unemployment"
---

# Unemployment API

Retrieve the official unemployment rate for one observation period.

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

## Endpoint and request

REST endpoint

```
GET /v1/economics/{country}/unemployment
```

Example request

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

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

## Parameters

The accepted period format for this operation is `YYYY, YYYY-MM, or 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, YYYY-MM, or 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-07",
  "rate": "4.1",
  "released_on": "2026-11-06"
}
```

| Field | Type | Required | Meaning |
| --- | --- | --- | --- |
| `country` | string | Yes | The requested uppercase ISO alpha-3 country code. |
| `period` | string | Yes | The official observation period returned. |
| `rate` | decimal string | Yes | The published rate, in percent, from 0 through 100. |
| `released_on` | date | Yes | The official publication date, not Narwhal's retrieval time. |
| `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. |
| `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: `["rate"]`. 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: Anguilla, Bulgaria, Guyana, Hungary, Iceland, Kazakhstan, Macao, Morocco, Taiwan, Uruguay, Vanuatu, Vietnam and Zambia. It has no history: a `period` or `version_id` request for such a country returns `404 series_not_found`.

Example request

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

Example response

```
{
  "country": "BGR",
  "period": "2026-Q3",
  "rate": "3.1",
  "released_on": "2026-11-13",
  "source": {
    "publisher": "National Statistical Institute"
  },
  "stage": "final",
  "published_at": "2026-11-13T09:00:00Z"
}
```

Example request

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

Example response

```
{
  "country": "DEU",
  "period": "2026-09",
  "rate": "4.1",
  "released_on": "2026-10-30",
  "source": {
    "publisher": "Statistisches Bundesamt"
  },
  "stage": "final",
  "published_at": "2026-10-30T08:55: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

35 Countries

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

The observation frequency follows each official national release.

### Annual World Bank history

163 Countries

`ABW, AFG, AGO, ALB, ARE, ARM, ASM, ATG, AZE, BDI, BEN, BFA, BGR, BHR, BHS, BIH, BLR, BLZ, BMU, BOL, BRB, BRN, BTN, BWA, CAF, CHN, CIV, CMR, COD, COG, COM, CPV, CRI, CUB, CUW, CYM, CYP, DJI, DMA, DOM, DZA, ECU, EGY, ERI, ETH, FJI, FRO, 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, KWT, LAO, LBN, LBR, LBY, LCA, LIE, LKA, LSO, MAC, MAR, MDA, MDG, MDV, MHL, MKD, MLI, MLT, MMR, MNE, MNG, MNP, MOZ, MRT, MUS, MWI, NAM, NCL, NER, NGA, NIC, NPL, NRU, OMN, PAK, PAN, PER, PLW, PNG, PRI, PRK, PRY, PSE, PYF, QAT, ROU, RUS, RWA, SDN, SEN, SLB, SLE, SLV, SMR, SOM, SRB, SSD, STP, SUR, SVK, SWZ, 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?
