Check if a date is a public holiday

Do it with the API

Use the date endpoint when you have a country and a date to test. Its response contains country, coverage and holidays. Read the entries in holidays to see which holiday applies, including its scope and any subdivisions, rather than treating every returned entry as a separate holiday date.

1. Get your API key Create a free key and keep it in the environment variable NARWHAL_API_KEY. Send it as Authorization: Bearer YOUR_KEY; the curl commands use that environment variable in the authorization header.
2. Request the date for the country Use GET /v1/calendars/holidays/{country}/on/{date} with the country and date you want. This request asks for holidays in the United Kingdom on 28 December 2026.
   curl, a holiday on a single date

   curl -s -H "Authorization: Bearer $NARWHAL_API_KEY" \
     "https://api.narwhalapi.com/v1/calendars/holidays/GBR/on/2026-12-28"

3. Read the holidays list An empty holidays list means the requested date is not a holiday there. A populated list gives the holiday entries for that date, so use their scopes and subdivisions when deciding whether they match the holiday calendar you need.
4. Find a holiday on or after a date Use the next endpoint when you need a holiday from a starting date, including that date itself. For the United States, from_date=2026-10-24 returns Veterans Day on 11 November 2026 in holiday.
   curl, a holiday on or after a date

   curl -s -H "Authorization: Bearer $NARWHAL_API_KEY" "https://api.narwhalapi.com/v1/calendars/holidays/USA/next?from_date=2026-10-24"

If a request returns an error, read the application/problem+json response. Its status, code and detail describe the error, and request_id identifies the request. Use the holiday list from a successful response to answer the date question; an error response does not give you that holiday result.

Do it in a sheet or without code

Look up the country on Narwhal holiday calendars if you want to find the date without an API request. Start with the country whose calendar you need: the Christmas week example uses separate United States and United Kingdom results, and the regional entries within a country can also matter.

In Excel or Sheets, use a column of holiday dates named Holidays and put the date to test in A2. The formula asks whether that date appears in the holiday column. Use the holiday list for the country you are checking, since the formula tests membership in the dates you give it.

=COUNTIF(Holidays, A2)>0

With a United States holiday list, the formula returns TRUE for 25 December 2026 and FALSE for 24 December 2026. Those results depend on the holiday dates in Holidays; the formula itself does not request a country calendar from the API.

A membership test only needs to know whether the date is present in your chosen list. If regional entries share a date, the formula still answers that question. To decide which region an entry applies to, read its subdivisions in the API response before using its date in your list.

Which option to use when

For the year-list approach, follow add a holiday check to your code. The date endpoint answers a question about a supplied date, while the next endpoint accepts a starting date and returns a holiday date. If your question is whether a particular date is a holiday, keep that date in the request. If your question is which holiday comes on or after it, supply it as from_date.

Why does the response list the same holiday more than once?

When holidays differ by region, the API returns an entry for each group of subdivisions. For Boxing Day observed on 28 December 2026 in the United Kingdom, it returns three entries: England and Wales together, Northern Ireland, and Scotland.

The subdivision codes are GB-ENG and GB-WLS for the shared entry, GB-NIR for Northern Ireland, and GB-SCT for Scotland. Each entry has scope bank and observed: true. These are regional entries for the same holiday date, so read the subdivision grouping alongside the name.

What does observed: true mean?

It means the date is the substitute day when a holiday falls on a weekend. Boxing Day, 26 December 2026, is a Saturday, so the bank holiday is Monday 28 December 2026.

For that example, use the observed bank holiday date when testing membership in a bank holiday calendar. The observed field explains why the returned date differs from the holiday's calendar date; both dates belong to the same Boxing Day example.

How do I leave out collective leave days?

Pass scope=national_public to leave Indonesia's collective leave days out of the results. Indonesia includes cuti bersama with their own collective_leave scope, so a request without that filter can include those days.

The optional scope filter limits results to a single scope. Available examples include national_public, bank, federal_government and collective_leave. Pick the scope that matches the calendar you need before interpreting the returned holiday entries.

Worked example: Christmas week 2026 in the United States and United Kingdom

Start with 24 December 2026 in the United States. Its empty list gives a negative holiday result. Then test 25 December 2026 for the same country: Christmas Day appears with scope federal_government, which gives a positive result for that calendar.

For the United Kingdom, test 25 December 2026 and read the Christmas Day entry with scope bank. Then test 28 December 2026 for the observed Boxing Day entries. Keep the country, date and scope together when recording each result.