Build an economic calendar

Do it with the API

Use the economic calendar for release dates. Each release has fields for its time, country and name, plus the period, topic, status and timezone. Keep those fields with the release if your product or dashboard needs more detail than the printed schedule.

1. Set your API key Get a free key and store it in the NARWHAL_API_KEY environment variable. The script reads that variable and sends the key as Authorization: Bearer YOUR_KEY to https://api.narwhalapi.com. Narwhal uses the same key for REST and MCP.
2. Choose the countries and dates Pass repeated countries parameters with start_date and end_date. The example uses USA, GBR and JPN for 9 to 13 November 2026. Change the country list and date arguments when you want a different schedule; keep the request pointed at /v1/economics/calendar.
3. Fetch and sort the releases Run the Python script with your key available in the environment. It collects the releases across pages, selects records that have at, and sorts the time, country and name together. The printed schedule uses UTC times, followed by the release count for the requested date range.
   Python, a week of releases for three countries

   import os
   import requests
   
   HEADERS = {"Authorization": f"Bearer {os.environ['NARWHAL_API_KEY']}"}
   
   def calendar(countries, start, end):
       cursor = None
       while True:
           params = {"countries": countries, "start_date": start, "end_date": end, "limit": 100}
           if cursor:
               params["cursor"] = cursor
           r = requests.get("https://api.narwhalapi.com/v1/economics/calendar", params=params, headers=HEADERS, timeout=10)
           r.raise_for_status()
           body = r.json()
           yield from body["releases"]
           cursor = body.get("next_cursor")
           if not cursor:
               return
   
   rows = sorted((x["at"], x["country"], x["name"]) for x in calendar(["USA", "GBR", "JPN"], "2026-11-09", "2026-11-13") if "at" in x)
   for at, country, name in rows:
       print(at, country, name)
   print(len(rows), "releases")

4. Choose the fields to display Show at (UTC), country, name, period, topic, status and timezone in a fuller calendar. The script prints only the time, country and name. Keep stage available when you need to distinguish editions of a release. The values array is empty until figures are published, so a scheduled release can appear before it has figures.

Use the website, a calendar app or a sheet

Open the economic calendar to read releases on the Narwhal website. There is an economic calendar page per country, so this is a direct route when you want to read a country's schedule without writing a request.

A calendar feed shows the same releases in your calendar app. Follow get an alert before an economic release for that route. If you prefer a sheet, it can hold the script's output: the UTC time, country and release name. The sheet route starts with the API output; the website and feed are available when you want to read the schedule without code.

Which option to use when

Why does GDP appear twice for the United Kingdom?

Two editions of a release can share a time, and stage tells them apart. For example, a first estimate and a monthly figure can have the same scheduled time. The field also distinguishes flash, advance, first and final editions, so the release name and time alone can leave editions looking alike.

Show stage or release_id alongside the name to distinguish the entries. On 12 November 2026 at 07:00 UTC, the United Kingdom schedule includes GDP twice. Preserve both entries in that schedule when you display its releases, with the edition or identifier visible beside each name.

How many releases does one request return?

A page returns up to 100 releases. Use limit to set the page size and pass cursor to continue through the results. A page is part of the requested schedule; use next_cursor to determine whether there are more releases to collect for the same countries and dates.

Continue until next_cursor is null or empty. If the API returns 409 cursor_expired, restart the request without the cursor. Keep your country and date selection in that request so you retrieve the schedule you asked for from the beginning.

Which countries can I include in the calendar?

Omit countries to get every covered country, or pass up to 50 country codes. Use EMU for the euro area.

The Python example supplies a country list, which becomes repeated countries parameters in the request. For an all-country calendar, omit that parameter from the request. Keep the date range in place and collect every page before sorting the releases by their UTC time.

Worked example: 9 to 13 November 2026

For 9 to 13 November 2026, count the United States entries first: Wholesale trade, Consumer prices, Wages and earnings, Jobless claims, Petroleum inventories, Public finances and Producer prices. That gives the United States 7 releases. Japan has Household spending and Balance of payments, for 2 releases in the same date range.

Count the United Kingdom's GDP entries separately. Together with Construction output, Goods and services trade, Industrial production and Services output, they give the United Kingdom 6 releases for 9 to 13 November 2026. Add the country counts to get the schedule's total.

Read the UTC times in date order. On 9 November 2026, USA Wholesale trade is at 15:00, JPN Household spending is at 23:30 and JPN Balance of payments is at 23:50. On 10 November 2026, USA Consumer prices and Wages and earnings share the 13:30 time. On 12 November 2026, USA Jobless claims is at 13:30, Petroleum inventories at 17:00 and Public finances at 19:00. USA Producer prices is at 13:30 on 13 November 2026.

For 9 to 13 November 2026, the busiest hour is 07:00 UTC on 12 November, with all 6 United Kingdom releases. In the sorted schedule, that group includes both GDP editions alongside Construction output, Goods and services trade, Industrial production and Services output.