The Calendar API

Free US holiday API with no key: federal and per-state holidays as static JSON files, each entry citing its statutory basis and observance rule. Tested example included.

No API key requiredCORS enabledHTTPSFree tier

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

What is the The Calendar API?

The Calendar publishes United States federal and state holidays as static JSON files needing no API key. Each holiday gives its date, weekday, the observed date where it shifts, and a note stating the rule that determines it, with the governing statute cited on the response.

The `source` field is what distinguishes this from other holiday feeds: the federal file cites `5 U.S.C. § 6103`, the statute that actually defines the holidays. When a date is disputed or someone in finance asks where a figure came from, being able to point at the legal basis rather than at an API is worth a surprising amount.

The `observed` field handles the case that trips most holiday code up. When a fixed-date holiday falls at a weekend, United States federal practice shifts the observance to the adjacent Friday or Monday — so Independence Day on a Saturday is observed on the Friday. `date` holds the actual holiday and `observed` holds the day off, and they are not always the same. The `note` field states the rule in plain English, such as "Third Monday in January", which makes the data self-explanatory. Everything is static per-year files, so there is no rate limiting and no query grammar to learn.

Quick facts

Base URL: https://the-calendar.net/api
Authentication: No API key and no account. These are static JSON files.
Rate limit: None. Static files with per-year granularity.
Pricing: Free.
CORS: Enabled — callable directly from browser JavaScript
Official docs: Read the docs

How to use the The Calendar 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 US federal holidays for a year

GET https://the-calendar.net/api/holidays/us-federal/2026.json

curl

curl 'https://the-calendar.net/api/holidays/us-federal/2026.json'

JavaScript (fetch)

const res = await fetch("https://the-calendar.net/api/holidays/us-federal/2026.json");
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://the-calendar.net/api/holidays/us-federal/2026.json", timeout=20)
res.raise_for_status()
print(res.json())

Response — HTTP 200 (truncated)

{
  "country": "US",
  "kind": "federal",
  "year": 2026,
  "source": "5 U.S.C. § 6103",
  "holidays": [
    {
      "name": "New Year's Day",
      "date": "2026-01-01",
      "observed": null,
      "weekday": "Thursday",
      "note": null
    },
    {
      "name": "Martin Luther King Jr. Day",
      "date": "2026-01-19",
      "observed": null,
      "weekday": "Monday",
      "note": "Third Monday in January"
    },
    {
      "name": "Presidents’ Day (Washington's Birthday)",
      "date": "2026-02-16",
      "observed": null,
      "weekday": "Monday",
      "note": "Third Monday in February"
    },
    {
      "name": "Memorial Day",
      "date": "2026-05-25",
      "observed": null,
      "weekday": "Monday",
      "note": "Last Monday in May"
    },
    {
      "name": "Juneteenth National Independence Day",
      "date": "2026-06-19",
      "observed": null,
      "weekday": "Friday",
      "note": null
    },
    {
      "name": "Independence Day",
      "date": "2026-07-04",
      "observed": "2026-07-03",
      "weekday": "Saturday",
      "note": null
    },
    {
      "name": "Labor Day",
      "date": "2026-09-07",
      "observed": null,
      "weekday": "Monday",
      "note": "First Monday in September"
    },
    {
      "name": "Columbus Day / Indigenous Peoples’ Day",
      "date": "2026-10-12",
      "observed": null,
      "weekday": "Monday",
      "note": "Second Monday in October"
    },
    {
      "name": "Veterans Day",
      "date": "2026-11-11",
      "observed": null,
      "weekday": "Wednesday",
      "note": null
    },
    {
      "

Parameters

Parameter	Type	Required	Description
`(kind)`	path	Required	`holidays/us-federal` for federal, or `holidays/by-state/{state}` for a single state. `holidays/us-federal`
`(year)`	path	Required	Year with a `.json` suffix. Several years either side of the present are published. `2026.json`
`/index.json`	path	Optional	Index of every file the API publishes, including which years and states exist.

Response fields

country / kind / yearstring / integer: Country code, whether the file is federal or state level, and the year it covers.
sourcestring: The statutory basis — `5 U.S.C. § 6103` for the federal file. Cite this rather than the API when a date is queried.
holidaysarray: The holidays for that year.
holidays[].namestring: Holiday name, including alternative forms where they exist.
holidays[].datestring: The actual date of the holiday, `YYYY-MM-DD`.
holidays[].observedstring: The observed date when it differs because the holiday falls at a weekend. Null when it does not shift — this is the field to use for working-day logic.
holidays[].weekdaystring: Day of the week the holiday falls on, spelled out.
holidays[].notestring: The rule in plain English, such as `Third Monday in January`. Null for fixed-date holidays.

What you can build with the The Calendar API

Calculate United States business days correctly, including observance shifts
Show federal and state holidays side by side
Cite the statutory basis for a holiday date in a compliance context
Pre-load several years of holidays into a scheduling system

Common errors and how to fix them

Wrong day off calculated

A holiday falling at a weekend shifts its observance.

Fix: Use `observed` when it is populated and `date` when it is null. Ignoring `observed` is the classic United States holiday bug.

404 on a year

Only a range of years around the present is published.

Fix: Fetch `/index.json` to see which years and states exist before requesting one.

State holidays missing

Federal and state files are separate.

Fix: The `us-federal` file covers federal holidays only. Fetch the relevant `by-state` file as well.

Name mismatch across sources

Some holidays carry parenthetical alternatives.

Fix: Match on `date` rather than on `name` when reconciling with another dataset.

The Calendar API — frequently asked questions

Is The Calendar API free?

Yes, free with no key. It is a set of static JSON files, so there is nothing to rate limit.

What is the difference between date and observed?

`date` is when the holiday actually falls; `observed` is the day off when it shifts because the holiday lands at a weekend. For working-day calculations you want `observed` where it is populated.

Where do the dates come from?

The federal file cites 5 U.S.C. § 6103 in its `source` field, which is the statute defining federal holidays. That makes the data traceable to law rather than to an unattributed feed.

Does it cover individual states?

Yes, through separate `holidays/by-state/{state}/{year}.json` files. The federal file covers only federal holidays.

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.

Add Business Days Calculator

Add or subtract working days from a date, skipping the weekend days you choose and any holidays you paste in, and see every single day that was skipped.

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.

The Calendar 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.