CalDays API

Free public holiday API with no key: every holiday for a country and year, plus long weekends and a multi-city clock, under CC BY 4.0. Tested example included.

No API key requiredCORS enabledHTTPSFree tier

Endpoint tested and returned HTTP 200 on 2026-08-21

What is the CalDays API?

CalDays returns public holidays for more than 195 countries with no API key. A country request gives every holiday for the current year as date and name pairs, with the country's locale and the CC BY 4.0 licence stated in the response.

Holiday APIs mostly restrict themselves to national public holidays, which is tidy but frequently wrong for anyone planning around actual working days. CalDays casts wider: the captured United States response includes state-level observances such as New Mexico Statehood Day and Town Meeting Day alongside the federal ones, which is more useful and more confusing in equal measure.

That breadth is the thing to plan around. Several holidays can share a date — Martin Luther King Jr. Day, Robert E. Lee Day and Confederate Heroes Day all fall on the same Monday in the sample — and the response does not tell you which subdivisions each applies to. If you need "is the office closed", filter to the ones you know are national. The `long-weekends` endpoint on the same base path does the useful derived work of finding holidays adjacent to weekends, and a `clock` endpoint returns current times for a comma-separated list of cities.

Quick facts

Base URL: https://caldays.com/api
Authentication: No API key and no account. CC BY 4.0 requires attribution when you republish the data.
Rate limit: No published limit. Holiday data changes annually — cache it for a long time.
Pricing: Free under CC BY 4.0.
CORS: Enabled — callable directly from browser JavaScript
Official docs: Read the docs

How to use the CalDays API

Every request below was executed against the live API on 2026-08-21, and the response shown is the real body it returned — not an illustration.

1. Fetch a country's public holidays

GET https://caldays.com/api/holidays/us

curl

curl 'https://caldays.com/api/holidays/us'

JavaScript (fetch)

const res = await fetch("https://caldays.com/api/holidays/us");
if (!res.ok) throw new Error(`Request failed: ${res.status}`);
const data = await res.json();
console.log(data);

Python (requests)

import requests

res = requests.get("https://caldays.com/api/holidays/us", timeout=20)
res.raise_for_status()
print(res.json())

Response — HTTP 200 (truncated)

{
  "code": "us",
  "country": "United States",
  "countryLocal": "United States",
  "locale": "en-US",
  "year": 2026,
  "license": "CC BY 4.0",
  "count": 26,
  "holidays": [
    {
      "date": "2026-01-01",
      "name": "New Year's Day"
    },
    {
      "date": "2026-01-06",
      "name": "New Mexico Statehood Day"
    },
    {
      "date": "2026-01-19",
      "name": "Martin Luther King Jr. Day"
    },
    {
      "date": "2026-01-19",
      "name": "Robert E. Lee Day"
    },
    {
      "date": "2026-01-19",
      "name": "Confederate Heroes Day"
    },
    {
      "date": "2026-02-16",
      "name": "Presidents' Day"
    },
    {
      "date": "2026-02-17",
      "name": "Mardi Gras"
    },
    {
      "date": "2026-03-03",
      "name": "Town Meeting Day"
    },
    {
      "date": "2026-03-26",
      "name": "Prince Jonah Kūhiō Day"
    },
    {
      "date": "2026-03-30",
      "name": "Seward's Day"
    },
    {
      "date": "2026-03-31",
      "name": "Cesar Chavez Day"
    },
    {
      "date": "2026-04-16",
      "name": "Emancipation Day"
    },
    {
      "date": "2026-04-20",
      "name": "Patriots' Day"
    },
    {
      "date": "2026-05-25",
      "name": "Memorial Day"
    },
    {
      "date": "2026-06-11",
      "name": "King Kamehameha Day"
    },
    {
      "date": "2026-06-19",
      "name": "Juneteenth"
    },
    {
      "date": "2026-07-03",
      "name": "Independence Day (obs.)"
    },
    {
      "date": "2026-07-04",
      "name": "Independence Day"
    },
    {
      "date": "2026-08-21",
      "name": "Statehood Day"
    },
    {

Parameters

Parameter	Type	Required	Description
`(country code)`	path	Required	Lowercase ISO 3166-1 alpha-2 country code. `us`
`(year)`	path	Optional	Append a year to the country path for a specific year. Defaults to the current one. `2027`
`/long-weekends/{cc}`	path	Optional	Holidays that fall adjacent to a weekend, already worked out.
`/clock`	path	Optional	Current time for a comma-separated list of city codes.

Response fields

code / country / countryLocalstring: ISO code, the English country name and the name in the local language.
localestring: BCP 47 locale such as `en-US`, useful for formatting the dates consistently.
yearinteger: The year the holidays cover.
countinteger: How many holidays are in the response — 26 for the United States in the captured example, well above the federal count.
holidaysarray: The holidays themselves.
holidays[].datestring: ISO date, `YYYY-MM-DD`.
holidays[].namestring: Holiday name in English. Several entries can share a date where regional observances coincide.
licensestring: `CC BY 4.0`, restated in every response.

What you can build with the CalDays API

Show upcoming public holidays for a user's country
Plan project timelines around non-working days
Find long weekends for a travel planning tool
Build a multi-country holiday calendar for a distributed team

Common errors and how to fix them

More holidays than expected

Regional and observance days are included alongside national ones.

Fix: The United States returns 26 rather than the 11 federal holidays. Filter to the ones you recognise as national if you need working days.

Several holidays on one date

Regional observances coincide.

Fix: Group by date when rendering, and expect a single day to carry multiple names.

404 on a country

Codes are lowercase ISO 3166-1 alpha-2.

Fix: Send `us`, not `USA` or `US`.

Attribution missing

CC BY 4.0 requires credit.

Fix: The `license` field appears in every response. Credit CalDays wherever you display the data.

CalDays API — frequently asked questions

Is the CalDays API free?

Yes, free with no key, published under CC BY 4.0. That licence requires attribution when you republish the data.

Why does the United States return 26 holidays?

Because it includes state-level and observance days as well as the 11 federal holidays. That is more complete but means you must filter if you specifically need federal non-working days.

How do I get a different year?

Append the year to the country path. Without it you get the current year.

What are long weekends?

A derived endpoint that finds holidays falling adjacent to a weekend, so you do not have to compute the bridging days yourself. It is on the same base path.

Tools that pair with this API

US Federal Holidays Calculator

List all eleven US federal holidays for any year with observed dates, weekend shifts applied under EO 11582, and one-click CSV or ICS calendar export.

Date Difference Calculator

Calculate the exact difference between two dates in years, months and days, plus total days, weeks, hours and minutes. Free, fast and private.

Printable Calendar Generator

Draw a printable month or full-year calendar with ISO week numbers and your own events, then export a print-ready PNG or PDF at A4 or Letter proportions.

CalDays is an independent third-party service and is not affiliated with ByteTools or ByteVancer. Details on this page were verified on 2026-08-21; always check the official documentation before relying on this API in production, as terms and limits can change.