Holiday Research

API de festivos

Read-only JSON API over HTTPS. Every request (except /api/v1/status) needs an API key, issued by the site administrator.

Authentication

curl -H "X-API-Key: hr_xxxxxxxxxxxx_…" "https://holiday-research.com/api/v1/occurrences?year=2031&lang=en"

Authorization: Bearer <key> also works. Keys in query strings are not accepted. Keep server keys on your server; browser keys must be restricted to your site's origins.

Endpoints

EndpointParameters
GET /api/v1/holidaysq, tradition, type, theme, country, region, level, language, nature, scope, updated_since, sort (name|date|updated), lang, page, per_page
GET /api/v1/holidays/{id|slug}lang, year (adds that year's occurrences)
GET /api/v1/occurrencesyear or from+to (13-month years, plan limit), country (adds that country's dates; international=0 for country only), all_jurisdictions=1, holiday (comma list of slugs/ids), tradition, type, theme, role (default primary,observed; also reference, eve, alternate), lang
GET /api/v1/ifc/years/{year}, /api/v1/ifc/yearsfrom, to — New Year's Day, Leap Day, solstice instant
GET /api/v1/convertdate=YYYY-MM-DD or ifc=2031-13-25 | 2031-NYD | 2031-LEAP | 2030-01-13 (transition year)
GET /api/v1/categories, /countries, /languageslang, type (categories: tradition, observance_level, holiday_type, theme). Tradition categories include symbol_url and flag_url (SVG, or null); see image credits for licenses.

13-month dates

Each date has an ifc object: year, month (1–13, Sol = 7), day (1–28), weekday (0 = Sunday), and special = new_year_day or leap_day for the two days outside the week (month/day/weekday are then null). code is a compact form such as 2031-13-25, 2031-NYD, 2031-LEAP. calendar is ifc13, transition or gregorian_only. 13-month dates up to 13-month year 2029 are projected backwards (proleptic: true). Gregorian 2030 is the transition year (calendar: transition): Gregorian months, 1 January kept, 2–12 January skipped, then each date is the Gregorian date + 11 days (code e.g. 2030-01-13, month 1–12); weekdays are the real weekdays. Gregorian 21–31 December 2029 have no 13-month date (calendar: gregorian_only, code null). 13-month year 2031 starts after New Year's Day on Gregorian 21 December 2030. See /api/v1/ifc/years/2030 → adoption.

Limits, caching and errors

Responses include X-RateLimit-Limit, X-RateLimit-Remaining and X-RateLimit-Reset. Over the limit you get 429 with Retry-After. Responses carry an ETag; send If-None-Match to get 304 Not Modified. Errors are JSON: {"error":{"code":"…","message":"…"}} with 400, 401, 403, 404, 405 or 429.