{"openapi":"3.0.3","info":{"title":"hldays","version":"1","x-logo":{"url":"https://api.hldays.dev/logo.svg","altText":"hldays"},"description":"Public holidays down to the municipality level, with a source on every entry. Supported countries: BR, DE, GB, GR, PT, US (see /v1/countries). Plans: BASIC (free) includes national and regional holidays and business-day calculations without municipal holidays (responses then carry a `notice`); paid plans include municipal holidays and religious and cultural observances (/v1/observances, and an `observances` list on the date endpoints; BASIC gets an `observances_notice` instead). Calls straight to https://api.hldays.dev without a key also work, on the BASIC plan's data and rate limited per IP."},"servers":[{"url":"https://api.hldays.dev"}],"paths":{"/ping":{"get":{"summary":"Health check. Public (no API key); returns status, server time and loaded data counts.","parameters":[],"responses":{"200":{"description":"OK","content":{"application/json":{}}},"400":{"description":"Invalid parameters","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"Not included in the caller's plan","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Unknown jurisdiction or country","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Free direct-access rate limit reached (see Retry-After)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/v1/countries":{"get":{"summary":"List supported countries with coverage statistics.","parameters":[],"responses":{"200":{"description":"OK","content":{"application/json":{}}},"400":{"description":"Invalid parameters","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"Not included in the caller's plan","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Unknown jurisdiction or country","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Free direct-access rate limit reached (see Retry-After)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/v1/countries/{code}":{"get":{"summary":"One country: weekend days, jurisdiction levels and coverage.","parameters":[{"name":"code","in":"path","required":true,"description":"ISO 3166-1 alpha-2 code.","schema":{"type":"string","enum":["BR","DE","GB","GR","PT","US"]}}],"responses":{"200":{"description":"OK","content":{"application/json":{}}},"400":{"description":"Invalid parameters","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"Not included in the caller's plan","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Unknown jurisdiction or country","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Free direct-access rate limit reached (see Retry-After)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/v1/jurisdictions":{"get":{"summary":"List jurisdictions (country, subdivisions, municipalities).","parameters":[{"name":"country","in":"query","required":false,"description":"ISO 3166-1 alpha-2 code.","schema":{"type":"string","enum":["BR","DE","GB","GR","PT","US"]}},{"name":"level","in":"query","required":false,"description":"country, subdivision or municipality.","schema":{"type":"string","enum":["country","subdivision","municipality"]}},{"name":"parent","in":"query","required":false,"description":"Parent jurisdiction id, e.g. PT-11.","schema":{"type":"string"}},{"name":"q","in":"query","required":false,"description":"Search by name or alias (accent-insensitive, partial match), up to 20 results, best first.","schema":{"type":"string"}}],"responses":{"200":{"description":"OK","content":{"application/json":{}}},"400":{"description":"Invalid parameters","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"Not included in the caller's plan","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Unknown jurisdiction or country","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Free direct-access rate limit reached (see Retry-After)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/v1/holidays":{"get":{"summary":"All holidays that apply in a jurisdiction in a year, including inherited regional and national ones.","parameters":[{"name":"jurisdiction","in":"query","required":true,"description":"Jurisdiction id (e.g. PT-M-1106) or name/alias (e.g. lisboa, Lisbon). Names prefer the most specific level.","schema":{"type":"string"}},{"name":"year","in":"query","required":false,"description":"Year 2016-2099. Default: current year.","schema":{"type":"integer","minimum":2016,"maximum":2099}},{"name":"country","in":"query","required":false,"description":"ISO 3166-1 alpha-2 code to disambiguate names across countries.","schema":{"type":"string","enum":["BR","DE","GB","GR","PT","US"]}},{"name":"types","in":"query","required":false,"description":"Comma-separated holiday types to include: public, local, optional. Default public,local.","schema":{"type":"string"}},{"name":"include_sources","in":"query","required":false,"description":"Include source/quote on each holiday (default true). false gives much smaller responses.","schema":{"type":"boolean"}}],"responses":{"200":{"description":"OK","content":{"application/json":{}}},"400":{"description":"Invalid parameters","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"Not included in the caller's plan","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Unknown jurisdiction or country","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Free direct-access rate limit reached (see Retry-After)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/v1/holidays/on":{"get":{"summary":"Every jurisdiction in a country with a holiday on a date (e.g. which municipalities are off today).","parameters":[{"name":"date","in":"query","required":true,"description":"Date YYYY-MM-DD.","schema":{"type":"string","format":"date"}},{"name":"country","in":"query","required":true,"description":"ISO 3166-1 alpha-2 code.","schema":{"type":"string","enum":["BR","DE","GB","GR","PT","US"]}},{"name":"types","in":"query","required":false,"description":"Comma-separated holiday types to include: public, local, optional. Default public,local.","schema":{"type":"string"}},{"name":"include_sources","in":"query","required":false,"description":"Include source/quote on each holiday (default true). false gives much smaller responses.","schema":{"type":"boolean"}},{"name":"traditions","in":"query","required":false,"description":"Comma-separated observance traditions: buddhist, chinese, christian, islamic, jewish, orthodox-christian. Default: all.","schema":{"type":"string"}}],"responses":{"200":{"description":"OK","content":{"application/json":{}}},"400":{"description":"Invalid parameters","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"Not included in the caller's plan","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Unknown jurisdiction or country","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Free direct-access rate limit reached (see Retry-After)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/v1/business-day":{"get":{"summary":"Whether a date is a business day in a jurisdiction, plus religious and cultural observances on that date (paid plans).","parameters":[{"name":"jurisdiction","in":"query","required":true,"description":"Jurisdiction id (e.g. PT-M-1106) or name/alias (e.g. lisboa, Lisbon). Names prefer the most specific level.","schema":{"type":"string"}},{"name":"date","in":"query","required":true,"description":"Date YYYY-MM-DD.","schema":{"type":"string","format":"date"}},{"name":"country","in":"query","required":false,"description":"ISO 3166-1 alpha-2 code to disambiguate names across countries.","schema":{"type":"string","enum":["BR","DE","GB","GR","PT","US"]}},{"name":"types","in":"query","required":false,"description":"Comma-separated holiday types to include: public, local, optional. Default public,local.","schema":{"type":"string"}},{"name":"include_sources","in":"query","required":false,"description":"Include source/quote on each holiday (default true). false gives much smaller responses.","schema":{"type":"boolean"}},{"name":"traditions","in":"query","required":false,"description":"Comma-separated observance traditions: buddhist, chinese, christian, islamic, jewish, orthodox-christian. Default: all.","schema":{"type":"string"}}],"responses":{"200":{"description":"OK","content":{"application/json":{}}},"400":{"description":"Invalid parameters","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"Not included in the caller's plan","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Unknown jurisdiction or country","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Free direct-access rate limit reached (see Retry-After)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/v1/business-days/add":{"get":{"summary":"Add (or subtract, if negative) business days to a date. The start date is not counted.","parameters":[{"name":"jurisdiction","in":"query","required":true,"description":"Jurisdiction id (e.g. PT-M-1106) or name/alias (e.g. lisboa, Lisbon). Names prefer the most specific level.","schema":{"type":"string"}},{"name":"from","in":"query","required":true,"description":"Date YYYY-MM-DD.","schema":{"type":"string","format":"date"}},{"name":"days","in":"query","required":true,"description":"Integer between -366 and 366.","schema":{"type":"integer","minimum":-366,"maximum":366}},{"name":"country","in":"query","required":false,"description":"ISO 3166-1 alpha-2 code to disambiguate names across countries.","schema":{"type":"string","enum":["BR","DE","GB","GR","PT","US"]}},{"name":"types","in":"query","required":false,"description":"Comma-separated holiday types to include: public, local, optional. Default public,local.","schema":{"type":"string"}},{"name":"traditions","in":"query","required":false,"description":"Comma-separated observance traditions: buddhist, chinese, christian, islamic, jewish, orthodox-christian. Default: all.","schema":{"type":"string"}}],"responses":{"200":{"description":"OK","content":{"application/json":{}}},"400":{"description":"Invalid parameters","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"Not included in the caller's plan","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Unknown jurisdiction or country","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Free direct-access rate limit reached (see Retry-After)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/v1/observances":{"get":{"summary":"Religious and cultural observances in a year (Christian, Orthodox, Jewish, Islamic, Chinese, Buddhist), as date spans. These are not days off by themselves. Islamic dates are calculated (estimated: true). Paid plans only.","parameters":[{"name":"year","in":"query","required":false,"description":"Year 2016-2099. Default: current year.","schema":{"type":"integer","minimum":2016,"maximum":2099}},{"name":"traditions","in":"query","required":false,"description":"Comma-separated observance traditions: buddhist, chinese, christian, islamic, jewish, orthodox-christian. Default: all.","schema":{"type":"string"}}],"responses":{"200":{"description":"OK","content":{"application/json":{}}},"400":{"description":"Invalid parameters","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"Not included in the caller's plan","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Unknown jurisdiction or country","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Free direct-access rate limit reached (see Retry-After)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/v1/observances/on":{"get":{"summary":"Religious and cultural observances on a date (including multi-day ones such as Ramadan or Passover). Paid plans only.","parameters":[{"name":"date","in":"query","required":true,"description":"Date YYYY-MM-DD.","schema":{"type":"string","format":"date"}},{"name":"traditions","in":"query","required":false,"description":"Comma-separated observance traditions: buddhist, chinese, christian, islamic, jewish, orthodox-christian. Default: all.","schema":{"type":"string"}}],"responses":{"200":{"description":"OK","content":{"application/json":{}}},"400":{"description":"Invalid parameters","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"Not included in the caller's plan","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Unknown jurisdiction or country","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Free direct-access rate limit reached (see Retry-After)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/v1/mcp":{"post":{"summary":"MCP server (Model Context Protocol, Streamable HTTP, JSON responses). Tools: list_countries, find_jurisdiction, get_holidays, holidays_on_date, is_business_day, add_business_days, get_observances. Send JSON-RPC 2.0 messages.","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","description":"JSON-RPC 2.0 message"},"example":{"jsonrpc":"2.0","id":1,"method":"tools/list"}}}},"parameters":[],"responses":{"200":{"description":"OK","content":{"application/json":{}}},"400":{"description":"Invalid parameters","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"Not included in the caller's plan","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Unknown jurisdiction or country","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Free direct-access rate limit reached (see Retry-After)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}}},"components":{"schemas":{"Error":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"}}}}}}}}