Get started in one request.

Quick start

Ask for the public holidays of a country and year. Add a region to get its complete set, nationwide days included.

curl "https://api.holibase.org/v1/public-holidays/DE/2026?subdivision=DE-BY&lang=en"

{
  "country": "DE",
  "subdivision": "DE-BY",
  "from": "2026-01-01",
  "to": "2026-12-31",
  "count": 12,
  "holidays": [
    {
      "date": "2026-01-06",
      "name": "Epiphany",
      "local_name": "Heilige Drei Könige",
      "category": "public",
      "scope": "regional",
      "is_observed": false,
      "is_estimated": false
    }
  ],
  "attribution": "Public holidays © python-holidays contributors (MIT). …"
}

From JavaScript, the API works directly in the browser. CORS is open for every origin.

const res = await fetch("https://api.holibase.org/v1/school-holidays/DE?subdivision=DE-BY");
const { periods } = await res.json();

Conventions

• Base URL is https://api.holibase.org/v1. The version only changes when a field changes meaning.
• Countries use ISO 3166-1 alpha-2 codes (US, DE), regions ISO 3166-2 codes (US-CA, DE-BY). Codes are case-insensitive.
• Dates are ISO 8601 calendar dates without a time zone. A holiday is the local day, wherever you are.
• Ranges are inclusive: end_date is the last day off.
• Names come in the language you ask for with lang, falling back to the base language, then English, then the local name. local_name is always in the country’s own language.

Public holidays

GET /v1/public-holidays/{country}/{year} returns one calendar year. Without the year, use from and to for any range up to three years.

# Next twelve months in California
curl "https://api.holibase.org/v1/public-holidays/US?subdivision=US-CA&from=2026-10-16&to=2027-10-15"

# Public and Catholic holidays in Austria
curl "https://api.holibase.org/v1/public-holidays/AT/2027?categories=public,catholic"

• scope is national or regional. Ask for a region or for the nation, never both in one call.
• is_observed marks a moved day off, such as a Sunday holiday observed on Monday.
• is_estimated marks dates that depend on moon sighting and can still move by a day or two.
• categories defaults to public. Depending on the country there are also bank, government, optional and religious categories.

School holidays

GET /v1/school-holidays/{country} returns school holiday periods for a region or a school authority. Without from and to you get the next twelve months.

# Lower Saxony
curl "https://api.holibase.org/v1/school-holidays/DE?subdivision=DE-NI"

# A US school district, by its Holibase id
curl "https://api.holibase.org/v1/school-holidays/US?authority={id}"

Each period has a kind:

• break: several days off, such as winter or summer holidays.
• holiday: a single day off school.
• teacher_day: no school for students, teachers work.
• early_release: school ends early. Not a day off.

The response also lists the calendars the periods come from, one per school year, with the first and last day of school, the source document and its origin: official (government open data), library (python-holidays), editorial (researched by Holibase) or community.

Coverage and unverified calendars

Every school holiday response has a coverage block. When there is no calendar for the scope, coverage.status is none and coverage.public_holidays links to the public holidays of the same region, so you can show those instead.

Researched calendars that have not been checked against a second source are pending and left out by default. Add include=pending to get them; they are marked status: "pending".

School districts and authorities

Where the school calendar is set below the state level, as for US school districts, Dutch regions or French zones, look up the authority first and pass its id.

curl "https://api.holibase.org/v1/authorities?country=US&q=gwinnett"
curl "https://api.holibase.org/v1/authorities/{id}"

q matches the name, the city or an official id such as the NCES district id. Results with a verified calendar rank first. Each result says which school years it has (school_years) and how many calendars are verified or pending.

Calendar feeds

Append .ics to a public or school holiday path, or add format=ics, and you get an iCalendar feed that Apple Calendar, Google Calendar and Outlook can subscribe to. Feeds cover last year to next year and roll forward by themselves.

https://api.holibase.org/v1/school-holidays/DE.ics?subdivision=DE-NI&lang=de
https://api.holibase.org/v1/public-holidays/US.ics?subdivision=US-NY

To subscribe in Apple Calendar, replace https:// with webcal://. The calendar page builds these links for any region or district.

Countries and coverage

• GET /v1/countries lists every country and region with its codes and names.
• GET /v1/coverage returns live coverage figures: public holiday countries and date range, school holiday coverage per country, and the US district directory. The coverage page shows the same figures.
• GET /v1/health tells you the API is up.

Caching and limits

• Responses are cached at the edge and carry an ETag. Send If-None-Match and you get 304 Not Modified when nothing changed.
• Public holidays are cached for a day, school holidays for six hours. Data is synced weekly, so there is no need to poll more often.
• Requests that miss the cache are limited to 120 per minute per IP address. Above that you get 429 with a Retry-After header. Cached responses do not count.
• For bulk use, cache on your side and fetch whole years rather than single days.

Errors

Errors use the HTTP status and a JSON body with a stable code and a message for people.

{ "error": { "code": "invalid_year", "message": "Year must have four digits, e.g. 2026." } }

• 400: a parameter is invalid. 404: unknown path, country or id.
• 429: rate limit, see above. 502 or 503: the database could not be reached, retry later.

Licence and credit

Holibase data is free to use, also commercially, under CC BY 4.0. Show the credit line from the attribution field where you display the data, for example in your footer or about page.

Public holidays are computed with python-holidays (MIT). Some school calendars come from government open data under their own open licences. The sources and licences page lists them all.