Free Holidays API: Get Public Holidays With No Key

I wanted a holidays API I could call without signing up for anything. Most of them want an account, a key and a plan. Nager.Date wants nothing. You call a URL and get JSON back.

TL;DR

One URL: https://nagerholidays.com/api/v4/Holidays/US/2027
Free, no key, 204 countries.
It returns 17 holidays for the US in 2027. 11 are nationwide.

The URL

Put a country code and a year in it:

https://nagerholidays.com/api/v4/Holidays/{countryCode}/{year}

Paste https://nagerholidays.com/api/v4/Holidays/US/2027 into your browser. The first holiday that comes back:

{
  "date": "2027-01-01",
  "name": "New Year's Day",
  "countryCode": "US",
  "nationalHoliday": true,
  "subdivisionCodes": null,
  "holidayTypes": ["Public", "Bank"]
}

nationalHoliday is true when it applies to the whole country.
subdivisionCodes lists the states or provinces when it doesn’t, like US-CA.
holidayTypes is Public, Bank, Observance, School and so on.

Other endpoints worth knowing (full reference):

/api/v4/Countries/Available: the 204 countries it covers.
/api/v4/Holidays/{countryCode}/Next: holidays in the next 365 days.

From the command line

curl https://nagerholidays.com/api/v4/Holidays/GB/2027

That returns 13 holidays for the UK in 2027.

From JavaScript

const res = await fetch('https://nagerholidays.com/api/v4/Holidays/CA/2027');
const holidays = await res.json();
console.log(holidays.length); // 31

From Python

import requests

holidays = requests.get('https://nagerholidays.com/api/v4/Holidays/AU/2027').json()
print(len(holidays))  # 27

The catches

Missing countries return nothing. United Arab Emirates and India come back as an empty response with status 204, not a list. JSON.parse on that throws. Check the status before you parse.
A bad code returns 404. XX gets “Unknown country code”.
Years. v4 covers about one year back and five years ahead, 2025 to 2031 right now. Ask for 2020 and you get a 400. The older v3 API covers more years but switches off on 31 January 2027.
Weekends. You get the actual date. Christmas 2027 comes back as Saturday 25 December. If your country moves the day off to Monday, the API won’t tell you.
Terms. Free for private and non profit use. Commercial use asks you to sponsor the project.

FAQ

Do I need an API key? No. Nager.Date is a public API. Call the URL and you get JSON.

How many countries does it cover?

Call /api/v4/Countries/Available for the list.

Which years can I ask for? v4 covers about 2025 to 2031. Other years return a 400.

What does a 204 response mean? The country isn’t covered yet, like United Arab Emirates or India. The response is empty, so check the status before you parse it.

Can I use it in a business? For commercial use, Nager.Date asks you to sponsor the project on GitHub.

It’s much easier in the sheet

All of that is fine if you’re writing an app. If you just want the holidays, I already did the work in Google Sheets.

Pick a country from a dropdown, or type =PUBLICHOLIDAYS("Canada", 2027) in a cell, and you get the list, with real dates, where each holiday applies, and a plain message instead of an error for the countries that aren’t covered. It also finds long weekends and counts working days.

The Holidays sheet showing all 16 public holidays in Japan in 2027 1. Japan in 2027, in the sheet: 16 holidays with local names and weekdays.

The full walkthrough is here: How to get public holidays into Google Sheets with a free API.

Copy the Holidays API sheet free. Free login, your own copy.

Then plan around these holidays with Big Year, my one page yearly calendar in Google Sheets.

Keep reading

How to Get Public Holidays Into Google Sheets With a Free API