Get an alert before an economic release

Do it with the API

1. Get your API key Get a free API key and keep it in the NARWHAL_API_KEY environment variable. Requests go to https://api.narwhalapi.com with Authorization: Bearer YOUR_KEY; the examples read the key from that variable.
2. Create a calendar feed Send POST /v1/calendars/subscriptions with your countries and date range. The example requests USA, the prices and policy_rate families, and no holidays, from 24 October 2026 through 23 October 2027.
   curl, create a calendar feed

   curl -s -X POST https://api.narwhalapi.com/v1/calendars/subscriptions \
     -H "Authorization: Bearer $NARWHAL_API_KEY" -H "Content-Type: application/json" \
     -d '{"countries":["USA"],"start_date":"2026-10-24","end_date":"2027-10-23","include_holidays":false,"families":["prices","policy_rate"]}'

3. Save the subscription details Save subscription_id, url and expires_at from the response. The .ics URL is returned once, so keep it and treat it as a secret.
4. Use the daily script for email or chat For a team channel alert, run this script once a day and send its output through your chat tool's incoming webhook. You can also send the output to email from your own code.
   Python, releases due in the next 24 hours

   import os, sys
   from datetime import datetime, timedelta, timezone
   import requests
   
   HEADERS = {"Authorization": f"Bearer {os.environ['NARWHAL_API_KEY']}"}
   COUNTRIES = ["USA", "GBR", "JPN"]
   AHEAD = timedelta(hours=24)
   
   def upcoming():
       now = datetime.now(timezone.utc)
       r = requests.get("https://api.narwhalapi.com/v1/economics/calendar", headers=HEADERS, timeout=10,
                        params={"countries": COUNTRIES, "start_date": now.date().isoformat(),
                                "end_date": (now + AHEAD).date().isoformat(), "limit": 100})
       r.raise_for_status()
       for x in r.json()["releases"]:
           if x["status"] == "scheduled" and "at" in x:
               at = datetime.fromisoformat(x["at"].replace("Z", "+00:00"))
               if now <= at <= now + AHEAD:
                   yield x, at
   
   for release, at in upcoming():
       print(f"{release['country']} {release['name']} ({release.get('period')}) at {at:%Y-%m-%d %H:%M} UTC")

Supply 1 to 50 alpha-3 country codes and inclusive start and end dates at most 366 days apart. The optional families filter accepts up to 5 families.

Expiry is 365 days after creation; a feed created on 24 October 2026 expires on 24 October 2027. Both include_releases and include_holidays default to true, and at least one must be true. The example turns holidays off and leaves releases included.

The script reads the calendar for USA, GBR and JPN, then prints scheduled releases with an at time within the next 24 hours. Each printed line includes the country, release name, period and UTC time. It prints nothing when no release is due.

The script uses UTC for its clock and the release timestamps. Its request covers the calendar dates from the time it runs through the end of the 24 hour look-ahead period, with a limit of 100.

The timestamp comparison includes both boundaries. A release without an at field is left out, as is a release whose status is not scheduled. The request calls raise_for_status() before reading the response, so an HTTP error stops it before it prints releases.

Set a reminder without code

Add the feed URL to your calendar app as a subscribed calendar. In Google Calendar, go to Other calendars > From URL and paste the .ics URL. Outlook and Apple Calendar have a subscribe to calendar from the web option. Use the URL returned by the subscription request.

The example feed contains USA releases in the prices and policy_rate families. To include holidays as well, use include_holidays with a value of true in the creation request. To request holidays alone, set include_releases to false and leave include_holidays true.

Set that calendar's default notification, for example 1 hour before a release. The reminder setting belongs to the calendar app. Creating the feed gives you the subscription URL; adding it to the app and setting the notification are the steps that make it a personal reminder.

Use the calendar subscriptions documentation for the feed request. If you want release times in your own zone, see convert a release time to your time zone.

Which option to use when

Webhooks report a release being added, moved or cancelled through release.scheduled, release.rescheduled and release.cancelled. They also report published data through dataset.published. They do not fire a timer before a release. Use a calendar reminder or the script for an advance alert, and use webhooks when you need those change or publication events.

Will the feed update when a release moves?

Yes, the calendar app refetches the feed on its own schedule, and the feed supports ETag refresh. The delay comes from the calendar client. A date change reaches the subscribed calendar when the app refreshes the feed; the app controls how often that happens.

How do I stop the calendar feed?

Call DELETE /v1/calendars/subscriptions/{subscription_id} to revoke it. The response is 204 and the feed stops. Use the subscription_id saved from the creation response for this request; the feed URL is the value you gave your calendar app.

How many requests does a calendar feed use?

Creating a feed uses one request, and revoking it uses one request. The calendar app's later fetches do not use your bearer key. Keep the feed URL secret even though the calendar app uses that URL to fetch the calendar.

Worked example: a 1 hour reminder for US CPI

Start with the US CPI release at 2026-11-10T13:30:00Z. Subtract 1 hour from 13:30 UTC to get the reminder time of 12:30 UTC on 10 November 2026. Set the subscribed calendar's default notification to 1 hour before the event.

For New York, the same reminder falls at 07:30 EST on 10 November 2026. In Jakarta it falls at 19:30 on 10 November 2026. These are the local times for the reminder; the release itself is at 13:30 UTC on that date.