Economic releases API reference
List scheduled releases and retrieve immutable publication versions with their original schedule precision.
Request
Browse the economic release calendar →
Both operations use your Narwhal bearer key. Each successful request costs one call on the Calendars API code, $2 per 1,000 calls. Product overview →
curl --request GET \
--url "https://api.narwhalapi.com/v1/economics/calendar?countries=USA&start_date=2026-10-01&end_date=2026-10-31&limit=25" \
--header "Authorization: Bearer $NARWHAL_API_KEY"GET /v1/economics/calendar/{release_id} retrieves one release. Add version_ to select a specific immutable version.
Parameters
| Parameter | Rule |
|---|---|
countries | Optional ISO alpha-3 codes. Repeat the query parameter for multiple countries; at most 50. |
start_ | Optional inclusive date window. Defaults to 30 days before today through 335 days after today; span at most 366 days. |
limit / | Page size 1–100, default 100. Continue with next_ and unchanged filters. |
release_ | Release detail uses a UUID path ID and an optional UUID version ID. |
404 not_ for an unknown release_. A malformed, tampered or filter-mismatched cursor returns 400 invalid_. A cursor older than 30 minutes or an unavailable snapshot returns 409 cursor_. Restart without the expired cursor.
Example response
Illustrative list response. The detail operation returns one release object with the same fields plus version and observed_.
{
"releases": [
{
"release_id": "00000000-0000-4000-8000-000000000201",
"revision": 0,
"country": "USA",
"series_id": "usa-consumer-prices",
"name": "Consumer prices",
"topic": "consumer_prices",
"family": "prices",
"period": "2026-09",
"status": "scheduled",
"at": "2026-10-14T12:30:00Z",
"timezone": "America/New_York",
"values": []
}
],
"next_cursor": null
}| Field | Rule |
|---|---|
name | name is Narwhal's standard English name from a closed list, such as Producer prices or Labour force survey, and contains no dates. |
series_ | series_ is Narwhal's permanent ID for the series, shared by every edition, such as tur-producer-prices. It is a slug, not a UUID, so / routes do not accept it. It is absent when the series has not yet been classified. |
topic | topic identifies what the series measures and is consistent across countries, such as consumer_, labour_, gdp, merchandise_ or policy_. It is absent when the series has not yet been classified, and new topics may be added. |
stage | stage identifies which edition of a period's figures the release contains: flash, advance, first, second, third, preliminary or final. It is absent for a single-edition release. |
at / | No timing field appears when the date is unknown or an estimated range has only a lower bound. at is the exact release time, date is the release day with no time set, between is an inclusive range of possible days as [from, to], or by is the latest possible day: a deadline, not a promised day. All timestamps are in UTC; timezone is the publisher's IANA time zone. |
period / | period is the period the release covers, at the level of detail the publisher provides: 2026-09 (month), 2026-Q3 (quarter), 2018-04/ (rolling range), 2026-09-12 (day or week), or 2025 (year). It is absent when the publisher states none. values is always present and is empty until figures are published; see Values below. |
date_ | date_ is indicative when the date comes from a third-party calendar and not from the publisher. An indicative date can still move. It is absent when the publisher or the central bank set the date. The publisher's date always wins over the third-party calendar. |
meeting | meeting is set on a central bank's policy meeting and holds the meeting's days from the bank's own calendar. kind is scheduled (the date is on the bank's calendar for the year), unscheduled or extraordinary. starts_ is the first day of a multi-day meeting, when the bank gives it, and ends_ is the last day, the day the decision is announced. |
revision / | revision increases each time the release's details change. It is 0 if the release has never been revised. GET / also returns version, the immutable version to pass back as version_, and observed_, when Narwhal last observed the release in the publisher's calendar. |
A field appears only when it has a value. Research articles and repeated datasets that some publishers list beside their releases are not included.
Schedule and status meaning
family is one of gdp, prices, labour, trade, yield_, policy_, activity, survey, housing, money, or public_. status is scheduled, published, or cancelled.
Timing uses the top-level at, date, between, or by field. Preserve timezone and the available bounds; by is a deadline, not a promised publication day. observed_ is when Narwhal last observed the release in the publisher's calendar.
Cancellation and rescheduling remain explicit versions. Do not fill an unknown time with midnight.
Narwhal's calendar sources European Central Bank (ECB) and Bank of Canada release dates and times from their respective websites, where they are available free of charge. In every response, each ECB release includes a notice field citing the ECB and stating the information is available free of charge at https://www.ecb.europa.eu.
Consensus, indicative dates and central bank meetings
Besides the publishers' own schedules, the calendar carries a third-party calendar. It adds a consensus forecast to figures, dates for releases the publishers do not list, and the days of central bank policy meetings. The publisher's date and figure always win over the third-party calendar.
This request returns the Bank Indonesia policy rate decision with a meeting object and a consensus on each rate, and a bank lending release whose date is indicative. Nothing is published yet, so actual is absent.
curl --request GET \\
--url "https://api.narwhalapi.com/v1/economics/calendar?countries=IDN&start_date=2026-11-18&end_date=2026-11-18" \\
--header "Authorization: Bearer $NARWHAL_API_KEY"{
"releases": [
{
"release_id": "7c9f64b5-bc4c-4875-9757-a5a3be9796dd",
"revision": 1,
"country": "IDN",
"series_id": "idn-policy-rate-decision",
"name": "Policy rate decision",
"topic": "policy_rate",
"family": "policy_rate",
"status": "scheduled",
"date": "2026-11-18",
"timezone": "Asia/Jakarta",
"values": [
{
"measure": "deposit_facility_rate",
"period": "2026-11",
"unit": "percent",
"previous": "5",
"consensus": "5"
},
{
"measure": "lending_facility_rate",
"period": "2026-11",
"unit": "percent",
"previous": "6.5",
"consensus": "6.75"
},
{
"measure": "policy_rate",
"period": "2026-11",
"unit": "percent",
"previous": "5.75",
"consensus": "6"
}
],
"meeting": {
"kind": "scheduled",
"ends_on": "2026-11-18"
}
},
{
"release_id": "ff160cc0-f950-4bde-8f98-73dbb6ff6423",
"revision": 1,
"country": "IDN",
"series_id": "idn-bank-lending",
"name": "Bank lending",
"topic": "money_credit",
"family": "money",
"period": "2026-10",
"status": "scheduled",
"date_basis": "indicative",
"at": "2026-11-18T07:30:00Z",
"timezone": "Asia/Jakarta",
"values": [
{
"measure": "bank_credit_yoy",
"unit": "percent",
"transformation": "year_over_year",
"previous": "13.26"
}
]
}
],
"next_cursor": null
}After a decision, a figure from the third-party calendar shows as provisional until the publisher's own release confirms it. This answer is the Bank Negara Malaysia decision of 5 November 2026.
curl --request GET \\
--url "https://api.narwhalapi.com/v1/economics/calendar?countries=MYS&start_date=2026-11-05&end_date=2026-11-05" \\
--header "Authorization: Bearer $NARWHAL_API_KEY"{
"releases": [
{
"release_id": "007f2565-07af-43df-b778-0abef890689a",
"revision": 1,
"country": "MYS",
"series_id": "mys-policy-rate-decision",
"name": "Policy rate decision",
"topic": "policy_rate",
"family": "policy_rate",
"status": "published",
"date_basis": "indicative",
"at": "2026-11-05T07:00:00Z",
"timezone": "Asia/Kuala_Lumpur",
"values": [
{
"measure": "policy_rate",
"period": "2026-11",
"unit": "percent",
"actual": "2.75",
"previous": "2.75",
"consensus": "2.75",
"provisional": true
}
]
}
],
"next_cursor": null
}Treat date_ and provisional as signs that a date or a figure can still change.
Release calendar coverage
The calendar covers 114 countries as of 13 November 2026. Official release schedules from statistical offices and central banks come first. A third-party calendar adds countries and releases that the publishers do not list in a form Narwhal can read. A date that comes only from the third-party calendar carries date_ indicative. Coverage varies by publisher and economic series; inclusion does not mean every indicator has a schedule. Filter the list request by country and date window to see the releases available in that snapshot.
Countries in the calendar · 114
AGO ALB ARE ARG ARM AUS AUT AZE BEL BGD BGR BHR BIH BLR BRA BWA CAN CHE CHL CHN COL CPV CRI CYP CZE DEU DNK DOM ECU EGY EMU ESP EST FIN FRA GBR GEO GHA GRC GTM HKG HRV HUN IDN IND IRL ISL ISR ITA JAM JOR JPN KAZ KEN KGZ KOR LBN LKA LSO LTU LUX LVA MAC MAR MDA MEX MKD MLT MNE MNG MOZ MUS MWI MYS NAM NGA NLD NOR NZL OMN PAK PER PHL PNG POL PRT PRY PSE ROU RUS RWA SAU SGP SLV SRB SUR SVK SVN SWE SWZ SYC THA TUN TUR TWN UGA UKR URY USA UZB VNM ZAF ZMB ZWE
Countries with a release calendar page · 114
- Albania · ALB
- Angola · AGO
- Argentina · ARG
- Armenia · ARM
- Australia · AUS
- Austria · AUT
- Azerbaijan · AZE
- Bahrain · BHR
- Bangladesh · BGD
- Belarus · BLR
- Belgium · BEL
- Bosnia and Herzegovina · BIH
- Botswana · BWA
- Brazil · BRA
- Bulgaria · BGR
- Cabo Verde · CPV
- Canada · CAN
- Chile · CHL
- China · CHN
- Colombia · COL
- Costa Rica · CRI
- Croatia · HRV
- Cyprus · CYP
- Czechia · CZE
- Denmark · DNK
- Dominican Republic · DOM
- Ecuador · ECU
- Egypt · EGY
- El Salvador · SLV
- Estonia · EST
- Eswatini · SWZ
- Euro area · EMU
- Finland · FIN
- France · FRA
- Georgia · GEO
- Germany · DEU
- Ghana · GHA
- Greece · GRC
- Guatemala · GTM
- Hong Kong · HKG
- Hungary · HUN
- Iceland · ISL
- India · IND
- Indonesia · IDN
- Ireland · IRL
- Israel · ISR
- Italy · ITA
- Jamaica · JAM
- Japan · JPN
- Jordan · JOR
- Kazakhstan · KAZ
- Kenya · KEN
- Kyrgyzstan · KGZ
- Latvia · LVA
- Lebanon · LBN
- Lesotho · LSO
- Lithuania · LTU
- Luxembourg · LUX
- Macao · MAC
- Malawi · MWI
- Malaysia · MYS
- Malta · MLT
- Mauritius · MUS
- Mexico · MEX
- Moldova · MDA
- Mongolia · MNG
- Montenegro · MNE
- Morocco · MAR
- Mozambique · MOZ
- Namibia · NAM
- Netherlands · NLD
- New Zealand · NZL
- Nigeria · NGA
- North Macedonia · MKD
- Norway · NOR
- Oman · OMN
- Pakistan · PAK
- Palestine · PSE
- Papua New Guinea · PNG
- Paraguay · PRY
- Peru · PER
- Philippines · PHL
- Poland · POL
- Portugal · PRT
- Romania · ROU
- Russia · RUS
- Rwanda · RWA
- Saudi Arabia · SAU
- Serbia · SRB
- Seychelles · SYC
- Singapore · SGP
- Slovakia · SVK
- Slovenia · SVN
- South Africa · ZAF
- South Korea · KOR
- Spain · ESP
- Sri Lanka · LKA
- Suriname · SUR
- Sweden · SWE
- Switzerland · CHE
- Taiwan · TWN
- Thailand · THA
- Tunisia · TUN
- Turkey · TUR
- Uganda · UGA
- Ukraine · UKR
- United Arab Emirates · ARE
- United Kingdom · GBR
- United States · USA
- Uruguay · URY
- Uzbekistan · UZB
- Vietnam · VNM
- Zambia · ZMB
- Zimbabwe · ZWE
An empty result means no releases are listed for that query in the snapshot. It does not guarantee that the publisher has no upcoming releases. Central bank meeting dates are served in this calendar as meeting. Public holidays, including bank holidays, and exchange closures are separate calendar datasets: see the public holidays reference and the exchange closures reference.
Values
Each release in the economic release calendar API includes a values array, empty until figures are published. Each value is a figure printed by the publisher: actual for the release's own period and previous for the period before. An actual that comes from a third-party calendar is marked provisional. Narwhal never computes these figures.
{
"values": [
{
"measure": "producer_price_change_mom",
"unit": "percent",
"transformation": "month_over_month",
"actual": "0",
"previous": "0.1",
"previous_revised_from": "0.2"
}
]
}| Field | Rule |
|---|---|
measure | measure identifies the figure within the release, such as producer_. |
concept | concept names what a figure measures, such as gdp or cpi, so the same figure has the same concept in every country. Read it with transformation and annualization to compare like with like. |
notice | notice contains source terms that the publisher requires with each access, such as the ECB's. Show it with the release. It is absent when there are no such terms. |
period | period appears only when the value covers a different period from the release period, as with continuing jobless claims, which cover the week before the release's own week. |
unit | unit is percent (a value of 1.2 means 1.2%), index (with index_, such as 2015=100), thousands, currency, ratio (for example, a jobs-to-applicants ratio), or balance (a survey net balance in points, not a percentage). |
currency / | currency (an ISO 4217 code) and scale (units, thousands, millions, hundred_, or billions) appear only when unit is currency. The figure uses the scale printed by the publisher. |
transformation | transformation is month_, year_, quarter_, three_, or change (a difference in levels, expressed in thousands, such as employment change). It is absent for a level. |
annualized / | annualized is true when the figure is at an annual rate, as with U.S. GDP growth. not_ is true when the figure is not seasonally adjusted. If annualized is absent, the figure is not annualized. If not_ is absent, the figure is seasonally adjusted, or, on a figure from a third-party calendar, the source does not say. |
actual / | actual is the figure for the release's own period; previous is the figure for the period before. Both are printed by the publisher, never computed by Narwhal. A figure the release does not state is absent; the next release then carries the earlier actual as its previous. |
consensus | consensus is the expected figure for the period, from a third-party calendar. It is a forecast and not a published figure. It is absent when no forecast is known, and it can appear on a value whose actual the publisher printed. |
provisional | provisional is true when actual has not been confirmed by the publisher's own release. The figure comes from a third-party calendar and can change when the publisher publishes. It is absent otherwise. |
previous_ | previous_ is the earlier figure as first printed, when this release revised previous. |
value_ | value_ appears only when actual is missing: pending_ after the scheduled time until the figure is captured, or unavailable when the release was published or cancelled without that figure. |
New values for these fields may be added over time, so clients should accept values they do not recognize.
Was this page helpful?