List the official holidays for a country and year, with...
List the official holidays for a country and year, with exact observed dates including substitute days (e.g. a Saturday July 4th observed on Friday). Query: country (ISO 3166-1 alpha-2, 200+ supported), year, optional region (subdivision code like CA for US-California or BY for DE-Bavaria), optional types filter (public, bank, school, optional, observance — comma-separated), optional lang (ISO 639-1) for localized names. Returns one item per holiday: { date (YYYY-MM-DD), name, type, substitute, rule }. Dates are computed from maintained per-country rules — including movable feasts and lunar-calendar holidays — so they stay correct year over year. Use for scheduling, delivery estimates, payment terms, and SLA math.
Request
- Base URL: https://2s.io
- URL: https://2s.io/api/calendar/holidays
- Auth: API key in header PAYMENT-SIGNATURE
Query parameters
ISO 3166-1 alpha-2 country code, e.g. US, DE, JP. 200+ countries supported.
Calendar year (1950-2100).
Optional subdivision code — e.g. CA for US-California, BY for DE-Bavaria, ON for CA-Ontario.
Optional comma-separated holiday-type filter: public, bank, school, optional, observance. Default: all types.
Optional ISO 639-1 language code for localized holiday names, e.g. en, de, fr.
Try before you buy. Set to 1 for one free real call per endpoint per hour — no wallet or payment needed — to verify the endpoint before paying. Equivalent to sending the "X-2s-Trial: 1" request header. Listed only on operations that offer a trial; the others always answer 402.
Response
Changes
No recorded changes to this operation across all 1 revision of this API.