{"openapi":"3.1.0","info":{"title":"Holibase API","version":"1.0.0","summary":"Public holidays and school holidays worldwide, free and open.","description":"Holibase is an open, non-profit database of public holidays and school holidays.\n\n* **Public holidays** for 247 countries and their regions, 2020 to ten years ahead, names in every language the source offers.\n* **School holidays** per region (German states, French zones, Dutch regions, ...) and per school authority (all ~19,600 US school districts are searchable; calendars exist for the largest ones).\n* **Calendar feeds** (iCalendar) for every query, ready to subscribe to in Apple Calendar, Google Calendar or Outlook.\n\nNo key, no sign-up. Responses are cached at the edge; please cache on your side too. Requests that miss the cache are limited to 120 per minute per IP.\n\n**Licence:** Holibase's own data is CC BY 4.0, holiday data from python-holidays is MIT, the US district directory is public domain (NCES). Credit \"Holibase (holibase.org), CC BY 4.0\" where you show the data; every response carries the exact `attribution` line.","contact":{"name":"Holibase","url":"https://holibase.org"},"license":{"name":"Data: CC BY 4.0 (own data), MIT (python-holidays)","url":"https://creativecommons.org/licenses/by/4.0/"}},"servers":[{"url":"https://api.holibase.org"}],"tags":[{"name":"Public holidays"},{"name":"School holidays"},{"name":"School authorities","description":"School districts, councils, zones and other bodies that set their own school calendar."},{"name":"Reference"}],"paths":{"/v1/countries":{"get":{"tags":["Reference"],"operationId":"listCountries","summary":"Countries and subdivisions","description":"Every country and subdivision (state, province, canton, region) Holibase knows, with codes and names.","responses":{"200":{"description":"Countries and subdivisions.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/CountriesResponse"}}}},"429":{"$ref":"#/components/responses/RateLimited"},"502":{"$ref":"#/components/responses/Upstream"}}}},"/v1/coverage":{"get":{"tags":["Reference"],"operationId":"getCoverage","summary":"What Holibase covers","description":"Live coverage figures: public holiday countries and date range, school holiday coverage per country, US district directory.","responses":{"200":{"description":"Coverage figures.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/CoverageResponse"}}}},"429":{"$ref":"#/components/responses/RateLimited"},"502":{"$ref":"#/components/responses/Upstream"}}}},"/v1/public-holidays/{country}/{year}":{"get":{"tags":["Public holidays"],"operationId":"getPublicHolidaysYear","summary":"Public holidays of one calendar year","description":"Public holidays of a country, or of one of its regions, for one calendar year. A region returns its complete set, nationwide holidays included (`scope` tells them apart).","parameters":[{"$ref":"#/components/parameters/country"},{"$ref":"#/components/parameters/year"},{"$ref":"#/components/parameters/subdivision"},{"$ref":"#/components/parameters/lang"},{"$ref":"#/components/parameters/categories"},{"$ref":"#/components/parameters/format"}],"responses":{"200":{"description":"JSON by default; an iCalendar feed with `.ics` or `format=ics`.","headers":{"ETag":{"schema":{"type":"string"}},"X-Cache":{"schema":{"type":"string","enum":["HIT","MISS"]}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/PublicHolidaysResponse"}},"text/calendar":{"schema":{"type":"string"},"example":"BEGIN:VCALENDAR\r\nVERSION:2.0\r\n...\r\nEND:VCALENDAR\r\n"}}},"304":{"description":"Not modified (If-None-Match matched the ETag)."},"400":{"$ref":"#/components/responses/BadRequest"},"404":{"$ref":"#/components/responses/NotFound"},"429":{"$ref":"#/components/responses/RateLimited"},"502":{"$ref":"#/components/responses/Upstream"}}}},"/v1/public-holidays/{country}":{"get":{"tags":["Public holidays"],"operationId":"getPublicHolidays","summary":"Public holidays in a date range","description":"Public holidays in a date range (at most three years). Without `from`/`to`: the current calendar year. Append `.ics` to the country (`/DE.ics`) or add `format=ics` to get an iCalendar feed instead of JSON. Without `from`/`to` a feed covers January 1 of last year to December 31 of next year, so a subscription moves forward by itself.","parameters":[{"$ref":"#/components/parameters/country"},{"$ref":"#/components/parameters/from"},{"$ref":"#/components/parameters/to"},{"$ref":"#/components/parameters/subdivision"},{"$ref":"#/components/parameters/lang"},{"$ref":"#/components/parameters/categories"},{"$ref":"#/components/parameters/format"}],"responses":{"200":{"description":"JSON by default; an iCalendar feed with `.ics` or `format=ics`.","headers":{"ETag":{"schema":{"type":"string"}},"X-Cache":{"schema":{"type":"string","enum":["HIT","MISS"]}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/PublicHolidaysResponse"}},"text/calendar":{"schema":{"type":"string"},"example":"BEGIN:VCALENDAR\r\nVERSION:2.0\r\n...\r\nEND:VCALENDAR\r\n"}}},"304":{"description":"Not modified (If-None-Match matched the ETag)."},"400":{"$ref":"#/components/responses/BadRequest"},"404":{"$ref":"#/components/responses/NotFound"},"429":{"$ref":"#/components/responses/RateLimited"},"502":{"$ref":"#/components/responses/Upstream"}}}},"/v1/school-holidays/{country}":{"get":{"tags":["School holidays"],"operationId":"getSchoolHolidays","summary":"School holidays of a region or school authority","description":"School holidays (breaks, single days off, teacher days, early release days) for a region (`subdivision`) or a school authority (`authority`, see /v1/authorities). Without either: the nationwide calendar, where one exists.\n\n`calendars` describes the school years found (first and last day of school, source, status); `periods` lists the days off. `coverage` says whether data exists at all, so an empty list is never mistaken for \"no holidays\".\n\nWithout `from`/`to`: today to twelve months ahead. Append `.ics` to the country (`/DE.ics`) or add `format=ics` to get an iCalendar feed instead of JSON. Without `from`/`to` a feed covers January 1 of last year to December 31 of next year, so a subscription moves forward by itself.","parameters":[{"$ref":"#/components/parameters/country"},{"$ref":"#/components/parameters/subdivision"},{"$ref":"#/components/parameters/authority"},{"$ref":"#/components/parameters/from"},{"$ref":"#/components/parameters/to"},{"$ref":"#/components/parameters/lang"},{"$ref":"#/components/parameters/include"},{"$ref":"#/components/parameters/format"}],"responses":{"200":{"description":"JSON by default; an iCalendar feed with `.ics` or `format=ics`.","headers":{"ETag":{"schema":{"type":"string"}},"X-Cache":{"schema":{"type":"string","enum":["HIT","MISS"]}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/SchoolHolidaysResponse"}},"text/calendar":{"schema":{"type":"string"},"example":"BEGIN:VCALENDAR\r\nVERSION:2.0\r\n...\r\nEND:VCALENDAR\r\n"}}},"304":{"description":"Not modified (If-None-Match matched the ETag)."},"400":{"$ref":"#/components/responses/BadRequest"},"404":{"$ref":"#/components/responses/NotFound"},"429":{"$ref":"#/components/responses/RateLimited"},"502":{"$ref":"#/components/responses/Upstream"}}}},"/v1/authorities":{"get":{"tags":["School authorities"],"operationId":"searchAuthorities","summary":"Search school authorities","description":"Find a school district or other school authority by name, city or official id (e.g. the US NCES LEAID). Matches by exact id first, then name prefix, then similarity; authorities with calendars and larger ones rank higher. Give at least `country` or `q`.","parameters":[{"name":"country","in":"query","schema":{"type":"string","pattern":"^[A-Za-z]{2}$"},"example":"US","description":"ISO 3166-1 alpha-2 code."},{"name":"q","in":"query","schema":{"type":"string","maxLength":80},"example":"gwinnett","description":"Name, city or official id."},{"$ref":"#/components/parameters/subdivision"},{"name":"limit","in":"query","schema":{"type":"integer","minimum":1,"maximum":100,"default":25}}],"responses":{"200":{"description":"Matching authorities.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/AuthoritySearchResponse"}}}},"400":{"$ref":"#/components/responses/BadRequest"},"429":{"$ref":"#/components/responses/RateLimited"},"502":{"$ref":"#/components/responses/Upstream"}}}},"/v1/authorities/{id}":{"get":{"tags":["School authorities"],"operationId":"getAuthority","summary":"One school authority","description":"An authority with the school calendars Holibase has for it.","parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string","format":"uuid"}}],"responses":{"200":{"description":"The authority and its calendars.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/AuthorityResponse"}}}},"400":{"$ref":"#/components/responses/BadRequest"},"404":{"$ref":"#/components/responses/NotFound"},"429":{"$ref":"#/components/responses/RateLimited"},"502":{"$ref":"#/components/responses/Upstream"}}}},"/v1/health":{"get":{"tags":["Reference"],"operationId":"health","summary":"Liveness","responses":{"200":{"description":"The API is up.","content":{"application/json":{"schema":{"type":"object","properties":{"status":{"const":"ok"}},"required":["status"]}}}}}}}},"components":{"parameters":{"country":{"name":"country","in":"path","required":true,"description":"ISO 3166-1 alpha-2 country code, case-insensitive. Append `.ics` for an iCalendar feed.","schema":{"type":"string","pattern":"^[A-Za-z]{2}(\\.ics)?$"},"example":"DE"},"year":{"name":"year","in":"path","required":true,"schema":{"type":"string","pattern":"^\\d{4}(\\.ics)?$"},"example":"2026"},"from":{"name":"from","in":"query","schema":{"type":"string","format":"date","examples":["2026-12-21"]},"description":"First day of the range (inclusive)."},"to":{"name":"to","in":"query","schema":{"type":"string","format":"date","examples":["2026-12-21"]},"description":"Last day of the range (inclusive). At most three years after `from`."},"subdivision":{"name":"subdivision","in":"query","example":"DE-BY","description":"ISO 3166-2 code within the country (case-insensitive). Named areas without an ISO code use slugs such as `DE-AUGSBURG`.","schema":{"type":"string"}},"authority":{"name":"authority","in":"query","schema":{"type":"string","format":"uuid"},"description":"Id of a school authority from /v1/authorities. Takes precedence over `subdivision`."},"lang":{"name":"lang","in":"query","example":"de","schema":{"type":"string"},"description":"Language for names (`de`, `en-US`, `pt-BR` ...). Falls back to the base language, then English, then the local name."},"categories":{"name":"categories","in":"query","example":"public,catholic","schema":{"type":"string"},"description":"Comma-separated holiday categories. Default `public`. Others, depending on the country: `bank`, `government`, `optional`, and religious categories such as `catholic`."},"include":{"name":"include","in":"query","schema":{"type":"string","enum":["pending"]},"description":"`pending` also returns calendars that are not verified yet (marked `status: pending`)."},"format":{"name":"format","in":"query","schema":{"type":"string","enum":["json","ics"],"default":"json"},"description":"`ics` returns an iCalendar feed."}},"responses":{"BadRequest":{"description":"A parameter is invalid.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"NotFound":{"description":"Unknown path or id.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"RateLimited":{"description":"Too many requests that missed the cache (120 per minute per IP). Retry after the `Retry-After` seconds.","headers":{"Retry-After":{"schema":{"type":"integer"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"Upstream":{"description":"The database could not be reached. Retry later.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"schemas":{"Error":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string","examples":["invalid_country","invalid_date","range_too_large","rate_limited"]},"message":{"type":"string"}},"required":["code","message"]}},"required":["error"]},"License":{"type":"object","properties":{"data":{"type":"string","examples":["CC-BY-4.0"]},"url":{"type":"string","format":"uri"},"attribution_required":{"type":"boolean"}},"required":["data","url","attribution_required"]},"PublicHoliday":{"type":"object","properties":{"date":{"type":"string","format":"date","examples":["2026-12-21"]},"name":{"type":"string","description":"Name in the requested language (with fallback)."},"local_name":{"type":"string","description":"Name in the country's default language."},"category":{"type":"string","examples":["public"]},"scope":{"type":"string","enum":["national","regional"],"description":"Nationwide holiday or one of this region only."},"is_observed":{"type":"boolean","description":"A substitute or moved day off (e.g. a holiday on a Sunday observed on Monday)."},"is_estimated":{"type":"boolean","description":"The date depends on moon sighting and can still move."},"subdivision_code":{"type":["string","null"]},"source_id":{"type":"string","examples":["python-holidays"]}},"required":["date","name","local_name","category","scope","is_observed","is_estimated","subdivision_code","source_id"]},"PublicHolidaysResponse":{"type":"object","properties":{"country":{"type":"string"},"subdivision":{"type":["string","null"]},"from":{"type":"string","format":"date","examples":["2026-12-21"]},"to":{"type":"string","format":"date","examples":["2026-12-21"]},"lang":{"type":["string","null"]},"categories":{"type":"array","items":{"type":"string"}},"count":{"type":"integer"},"holidays":{"type":"array","items":{"$ref":"#/components/schemas/PublicHoliday"}},"attribution":{"type":"string","description":"Credit line to show where the data is displayed."},"license":{"$ref":"#/components/schemas/License"}},"required":["country","subdivision","from","to","lang","categories","count","holidays","attribution","license"]},"SchoolPeriod":{"type":"object","properties":{"start_date":{"type":"string","format":"date","examples":["2026-12-21"]},"end_date":{"type":"string","format":"date","examples":["2026-12-21"],"description":"Inclusive."},"name":{"type":"string"},"kind":{"type":"string","enum":["break","holiday","teacher_day","early_release","other"],"description":"`break`: several days off. `holiday`: a single day off. `teacher_day`: no school for students. `early_release`: school ends early. `other`: another closure."},"school_year":{"type":"string","examples":["2026-27","2027"]},"calendar_id":{"type":"string","format":"uuid"},"origin":{"type":"string","enum":["official","editorial","community","library"]},"status":{"type":"string","enum":["confirmed","pending"]},"confirmations":{"type":"integer"},"source_url":{"type":["string","null"]}},"required":["start_date","end_date","name","kind","school_year","calendar_id","origin","status","confirmations","source_url"]},"SchoolCalendar":{"type":"object","properties":{"calendar_id":{"type":"string","format":"uuid"},"school_year":{"type":"string"},"origin":{"type":"string","enum":["official","editorial","community","library"],"description":"`official`: government open data. `editorial`: researched by Holibase. `community`: submitted. `library`: python-holidays."},"status":{"type":"string","enum":["confirmed","pending"]},"first_day":{"type":["string","null"],"format":"date","examples":["2026-12-21"]},"last_day":{"type":["string","null"],"format":"date","examples":["2026-12-21"]},"title":{"type":["string","null"]},"source_url":{"type":["string","null"]},"source_retrieved_at":{"type":["string","null"],"format":"date-time"},"notes":{"type":["string","null"]}},"required":["calendar_id","school_year","origin","status","first_day","last_day","title","source_url","source_retrieved_at","notes"]},"Coverage":{"oneOf":[{"title":"available","type":"object","properties":{"status":{"const":"available"},"school_years":{"type":"array","items":{"type":"string"}},"unverified":{"type":"boolean","description":"At least one returned calendar is pending."}},"required":["status","school_years","unverified"]},{"title":"none","type":"object","properties":{"status":{"const":"none"},"school_years":{"type":"array","maxItems":0},"message":{"type":"string"},"pending_available":{"type":"boolean","description":"Unverified calendars exist; request them with `include=pending`."},"public_holidays":{"type":"string","format":"uri","description":"The public holidays of the same region and range."}},"required":["status","school_years","message","pending_available","public_holidays"]}]},"SchoolHolidaysResponse":{"type":"object","properties":{"country":{"type":"string"},"subdivision":{"type":["string","null"]},"authority":{"type":["string","null"],"format":"uuid"},"from":{"type":"string","format":"date","examples":["2026-12-21"]},"to":{"type":"string","format":"date","examples":["2026-12-21"]},"lang":{"type":["string","null"]},"include_pending":{"type":"boolean"},"coverage":{"$ref":"#/components/schemas/Coverage"},"count":{"type":"integer"},"calendars":{"type":"array","items":{"$ref":"#/components/schemas/SchoolCalendar"}},"periods":{"type":"array","items":{"$ref":"#/components/schemas/SchoolPeriod"}},"attribution":{"type":"string","description":"Credit line to show where the data is displayed."},"license":{"$ref":"#/components/schemas/License"}},"required":["country","subdivision","authority","from","to","lang","include_pending","coverage","count","calendars","periods","attribution","license"]},"AuthoritySummary":{"type":"object","properties":{"id":{"type":"string","format":"uuid"},"country_code":{"type":"string"},"subdivision_code":{"type":["string","null"]},"kind":{"type":"string","enum":["school_district","local_authority","school_board","academy_trust","other"]},"name":{"type":"string"},"city":{"type":["string","null"]},"student_count":{"type":["integer","null"]},"external_ids":{"type":"object","additionalProperties":true,"description":"Official ids and facts, e.g. `nces_leaid`, `nces_name`, `county`, `lat`, `lon`, `grades`, `calendar_feed_url`."},"school_years":{"type":"array","items":{"type":"string"},"description":"School years with a calendar (confirmed or pending)."},"calendars_confirmed":{"type":"integer"},"calendars_pending":{"type":"integer"}},"required":["id","country_code","subdivision_code","kind","name","city","student_count","external_ids","school_years","calendars_confirmed","calendars_pending"]},"AuthoritySearchResponse":{"type":"object","properties":{"country":{"type":["string","null"]},"subdivision":{"type":["string","null"]},"q":{"type":["string","null"]},"count":{"type":"integer"},"authorities":{"type":"array","items":{"$ref":"#/components/schemas/AuthoritySummary"}}},"required":["country","subdivision","q","count","authorities"]},"AuthorityResponse":{"type":"object","properties":{"authority":{"type":"object","properties":{"id":{"type":"string","format":"uuid"},"country_code":{"type":"string"},"subdivision_code":{"type":["string","null"]},"kind":{"type":"string"},"name":{"type":"string"},"city":{"type":["string","null"]},"student_count":{"type":["integer","null"]},"website_url":{"type":["string","null"]},"external_ids":{"type":"object","additionalProperties":true}},"required":["id","country_code","subdivision_code","kind","name","city","student_count","website_url","external_ids"]},"calendars":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string","format":"uuid"},"school_year":{"type":"string"},"status":{"type":"string","enum":["confirmed","pending"]},"origin":{"type":"string"},"first_day":{"type":["string","null"],"format":"date","examples":["2026-12-21"]},"last_day":{"type":["string","null"],"format":"date","examples":["2026-12-21"]},"source_url":{"type":["string","null"]}},"required":["id","school_year","status","origin","first_day","last_day","source_url"]}}},"required":["authority","calendars"]},"Country":{"type":"object","properties":{"code":{"type":"string"},"alpha3":{"type":["string","null"]},"names":{"type":"object","additionalProperties":{"type":"string"},"description":"Name per language tag."},"default_language":{"type":["string","null"]},"languages":{"type":["array","null"],"items":{"type":"string"}},"holiday_categories":{"type":["array","null"],"items":{"type":"string"}},"school_holiday_level":{"type":["string","null"]},"updated_at":{"type":"string","format":"date-time"}},"required":["code","names"]},"Subdivision":{"type":"object","properties":{"code":{"type":"string","examples":["DE-BY"]},"country_code":{"type":"string"},"parent_code":{"type":["string","null"]},"source_code":{"type":["string","null"]},"name":{"type":["string","null"]},"names":{"type":["object","null"],"additionalProperties":{"type":"string"}},"kind":{"type":["string","null"]},"iso_verified":{"type":["boolean","null"]},"updated_at":{"type":"string","format":"date-time"}},"required":["code","country_code"]},"CoverageResponse":{"type":"object","properties":{"public_holidays":{"type":"object","properties":{"countries":{"type":"integer"},"subdivisions":{"type":"integer"},"first_date":{"type":"string","format":"date","examples":["2026-12-21"]},"last_date":{"type":"string","format":"date","examples":["2026-12-21"]}},"required":["countries","subdivisions","first_date","last_date"]},"school_holidays":{"type":"object","properties":{"countries":{"type":"integer"},"calendars":{"type":"integer","description":"Verified school calendars (one per scope and school year)."},"by_country":{"type":"array","items":{"type":"object","properties":{"country_code":{"type":"string"},"name":{"type":["string","null"]},"scopes":{"type":"integer","description":"Regions and authorities with a calendar."},"scopes_verified":{"type":"integer"},"authorities":{"type":"integer"},"first_school_year":{"type":["string","null"]},"last_school_year":{"type":["string","null"]},"origins":{"type":"array","items":{"type":"string","enum":["official","editorial","community","library"]}}},"required":["country_code","name","scopes","scopes_verified","authorities","first_school_year","last_school_year","origins"]}}},"required":["countries","calendars","by_country"]},"us_districts":{"type":"object","properties":{"directory":{"type":"integer","description":"Active US school districts and agencies (NCES)."},"verified":{"type":"integer","description":"Districts with a verified calendar."},"students":{"type":["integer","null"]},"students_verified":{"type":["integer","null"]}},"required":["directory","verified","students","students_verified"]},"generated_at":{"type":"string","format":"date-time"}},"required":["public_holidays","school_holidays","us_districts","generated_at"]},"CountriesResponse":{"type":"object","properties":{"countries":{"type":"array","items":{"$ref":"#/components/schemas/Country"}},"subdivisions":{"type":"array","items":{"$ref":"#/components/schemas/Subdivision"}}},"required":["countries","subdivisions"]}}}}