All APIs

Public holidays API

Get public holidays by country and year through REST or MCP. Check a date or find the next holiday with national and regional scope.

First request

Quickstart →
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 Illustrative response · not a live request
{
  "country": "IDN",
  "from_date": "2026-08-01",
  "coverage": [
    {
      "scope": "national_public",
      "nationwide": true,
      "subdivision_codes": []
    },
    {
      "scope": "collective_leave",
      "nationwide": true,
      "subdivision_codes": []
    }
  ],
  "holiday": {
    "date": "2026-08-17",
    "name": "Independence Day",
    "local_name": "Hari Kemerdekaan",
    "subdivision_codes": [],
    "nationwide": true,
    "observed": null,
    "scope": "national_public"
  }
}

Calendar subscriptions

Create a subscribed ICS feed through Narwhal API for your team's chosen countries and date window. Include available public holidays, economic release dates, or both. Use it in Google Calendar, Apple Calendar, Outlook, or other calendar clients.

curl --request POST \
  --url "https://api.narwhalapi.com/v1/calendars/subscriptions" \
  --header "Authorization: Bearer $NARWHAL_API_KEY" \
  --header "Content-Type: application/json" \
  --data '{"countries":["USA"],"start_date":"2026-09-01","end_date":"2026-12-31","include_releases":true,"include_holidays":true}'
Example response Illustrative response · not a live request
{
  "subscription_id": "example-subscription",
  "url": "https://api.narwhalapi.com/v1/calendars/subscriptions/EXAMPLE_TOKEN.ics",
  "expires_at": "2026-12-31T23:59:59Z",
  "refresh_note": "calendar clients control refresh latency"
}

Endpoints

GETList a published holiday year./v1/calendars/holidays/{country}/{year}
API reference →
GETFind holidays on a date./v1/calendars/holidays/{country}/on/{date}
API reference →
GETFind the next holiday./v1/calendars/holidays/{country}/next
API reference →

Sources and methodology

Check a date

Find holidays on a selected day while retaining national and regional scope.

Find what comes next

Request the next holiday from a chosen date instead of scanning a full year.

Coverage

View coverage →

Check the reference for published country-year coverage. National and regional events remain distinguishable. A public holiday does not establish bank, exchange, or settlement closure.

ARGAUSBRACANCHNDEUFRAGBRHKGIDNITAJPNINDMEXNLDNZLKORRUSSAUSGPTURESTIRLLVALTUUSAZAFPOLCZESVNHRVPRTAUTBELCOLDNKESPLUXNORSVKSWETWNPHL

Explore related pages

Economic calendar API

Track scheduled economic releases and their publication status. Build a release calendar for GDP, prices, labour, trade, and yield curves without treating uncertain schedules as exact times.

Explore the API →

Common questions

Are regional holidays included?

Where published coverage includes regional events, the response retains the applicable subdivisions.

What happens if a country or year is missing?

Unavailable calendar coverage returns an error. It does not imply that the country has no holidays.

Does a public holiday mean banks or markets are closed?

No. Public holidays, bank holidays, and exchange closures can follow different calendars. Use the published scope for the country and year you need.

Make your first request

Get a free API key →