All APIs

Calendars and holidays API

Public holidays, economic release schedules, and subscribed calendars.

Online99.88% uptime, last 30 days282 ms typical response

First request

Find the next holiday

curl --request GET \
  --url "https://api.narwhalapi.com/v1/calendars/holidays/IDN/next?from_date=2026-08-01" \
  --header "Authorization: Bearer $NARWHAL_API_KEY"
Example response
{
  "country": "IDN",
  "coverage": [
    {
      "scope": "collective_leave",
      "subdivision_codes": []
    },
    {
      "scope": "national_public",
      "subdivision_codes": []
    }
  ],
  "holiday": {
    "date": "2026-08-17",
    "name": "Independence Day",
    "holiday_key": "independence_day",
    "local_name": "Proklamasi Kemerdekaan",
    "subdivision_codes": [],
    "scope": "national_public"
  }
}

Endpoints

Holiday API

GETList a published holiday year/v1/calendars/holidays/{country}/{year}

List a published holiday year.

Parameters

  • countryrequired

    Three-letter country code, such as IDN or JPN.

  • yearrequired

    A published year, such as 2026.

  • scopeoptional

    Only one kind of day: national_public, regional_public, bank, collective_leave and others. Leave it out to get every kind.

Each holiday in the list

  • datedate

    The local calendar date of the holiday.

  • namestring

    The holiday name in English.

  • holiday_keystring

    The same key for the same holiday in every country, such as christmas_day.

  • local_namestring

    The name in the local language, when the government publishes one.

  • scopestring

    What kind of day it is, such as national_public, bank or collective_leave.

  • subdivision_codesarray

    Regions where it applies, such as GB-SCT. Empty means the whole country.


Full reference →
GETFind holidays on a date/v1/calendars/holidays/{country}/on/{date}

Find holidays on a date.

Parameters

  • countryrequired

    Three-letter country code, such as IDN or JPN.

  • daterequired

    The day to check, as YYYY-MM-DD.

  • scopeoptional

    Only one kind of day: national_public, regional_public, bank, collective_leave and others. Leave it out to get every kind.

Each holiday in the list

  • datedate

    The local calendar date of the holiday.

  • namestring

    The holiday name in English.

  • holiday_keystring

    The same key for the same holiday in every country, such as christmas_day.

  • local_namestring

    The name in the local language, when the government publishes one.

  • scopestring

    What kind of day it is, such as national_public, bank or collective_leave.

  • subdivision_codesarray

    Regions where it applies, such as GB-SCT. Empty means the whole country.


Full reference →
GETFind the next holiday/v1/calendars/holidays/{country}/next

Find the next holiday.

Parameters

  • countryrequired

    Three-letter country code, such as IDN or JPN.

  • from_daterequired

    Start from this day, as YYYY-MM-DD. The day itself counts.

  • scopeoptional

    Only one kind of day: national_public, regional_public, bank, collective_leave and others. Leave it out to get every kind.

Each holiday in the list

  • datedate

    The local calendar date of the holiday.

  • namestring

    The holiday name in English.

  • holiday_keystring

    The same key for the same holiday in every country, such as christmas_day.

  • local_namestring

    The name in the local language, when the government publishes one.

  • scopestring

    What kind of day it is, such as national_public, bank or collective_leave.

  • subdivision_codesarray

    Regions where it applies, such as GB-SCT. Empty means the whole country.


Full reference →

Economic calendar API

GETList releases/v1/economics/calendar

List releases in a date window.

Parameters

  • countriesoptional

    ISO alpha-3 codes, such as USA. Repeat the parameter for several countries, at most 50.

  • start_dateoptional

    First day of the window. The window starts 30 days before today by default.

  • end_dateoptional

    Last day of the window. It ends 335 days after today by default. The window spans at most 366 days.

  • limitoptional

    Releases per page, 1 to 100. The default is 100.

  • cursoroptional

    Continue with next_cursor and the same filters.

Each release in the list

  • release_idstring

    The release to read in detail.

  • namestring

    Narwhal’s standard English name, such as Producer prices. It contains no dates.

  • topicstring

    What the series measures, the same in every country, such as consumer_prices or gdp.

  • periodstring

    The period the release covers, such as 2026-09 or 2026-Q3.

  • statusstring

    Where the release stands, such as scheduled.

  • at / date / between / bystring

    The timing the publisher gave: an exact time, a day, a range of days or a deadline. None appears when the date is unknown.

  • valuesarray

    The published figures. The array is empty until they are out.


Full reference →
GETGet one release/v1/economics/calendar/{release_id}

Read a release, optionally selecting version_id.

Parameters

  • release_idrequired

    The release’s UUID.

  • version_idoptional

    The UUID of an earlier version. Without it you get the current one.

The release

  • versionstring

    The immutable version, which you can pass back as version_id.

  • namestring

    Narwhal’s standard English name, such as Producer prices. It contains no dates.

  • topicstring

    What the series measures, the same in every country, such as consumer_prices or gdp.

  • periodstring

    The period the release covers, such as 2026-09 or 2026-Q3.

  • statusstring

    Where the release stands, such as scheduled.

  • at / date / between / bystring

    The timing the publisher gave: an exact time, a day, a range of days or a deadline. None appears when the date is unknown.

  • valuesarray

    The published figures. The array is empty until they are out.


Full reference →

Holiday and economic calendar feeds

POSTCreate a subscription using your Narwhal API key and receive its ICS feed URL once/v1/calendars/subscriptions

Create a subscription using your Narwhal API key and receive its ICS feed URL once.


Full reference →
GETFetch the ICS feed/v1/calendars/subscriptions/{token}.ics

Fetch the ICS feed.


Full reference →
DELETERevoke a subscription/v1/calendars/subscriptions/{subscription_id}

Revoke a subscription.


Full reference →

Use cases

An economic calendar

Build a calendar of releases for the countries and dates you choose.

Read the guide →

Next CPI release date

Find when the next US CPI is due, in UTC and New York time.

Read the guide →

Alerts before a release

Get a reminder before a release from a calendar feed or a daily script.

Read the guide →

Working days between dates

Count the working days in a pay period or a leave request.

Read the guide →

Holidays for several countries

See which days each office is closed before you plan a release or a meeting.

Read the guide →

Is this date a holiday?

Get a yes or no for one date, with regional and observed days handled.

Read the guide →

Settlement business days

Find the settlement date of a trade around weekends and market holidays.

Read the use case →

Payroll and public holidays

Know which public holidays apply to staff in each country.

Read the use case →

Related APIs

Economic calendar API

Release dates and status for GDP, prices, labour, trade and yield curves.

Explore the API →

Public Holidays API

Official public holidays by country, with national and regional scope.

Explore the API →

Pricing

$10 of free credit a month, then from $2 per 1,000 calls.

See pricing →

FAQ

Can I add these dates to my calendar?

Create a calendar subscription to receive a revocable ICS feed for public holidays, economic releases, or both.

Does every economic release have an exact time?

No. The schedule preserves the publisher’s precision instead of assigning an invented time.

What should I check before using the data?

Holiday coverage is published by country and year. Release schedules may specify an exact time, a date, a range, or a deadline. Public holidays do not establish bank or exchange closure.