Public holidays by country

Whether a date is a day off in a country or one of its regions, and the reason; or every public holiday of a year.

curl "https://agent-helper.org/holidays/de/2026-10-03"

day off
# DE 2026-10-03 (sat)
# type: reference-data
# source: Nager.Date (with manual overrides)
# as-of: retrieved 2026-09-16T18:20:10Z
# reason: German Unity Day (Tag der Deutschen Einheit)
# weekend: sat,sun (built-in table (Saturday-Sunday unless known otherwise))
# license: https://github.com/nager/Nager.Date/blob/main/LICENSE.md

The trap

A list of public holidays answers a narrower question than the one usually asked. The real question is whether people will be at work on a given day, and a holiday list gets that wrong in four common ways.

Holidays move. When 4 July falls on a Saturday, as it does in 2026, the United States observes the federal holiday on Friday 3 July. The United Kingdom moves a bank holiday that lands on a weekend to the next Monday. Germany does not move them at all. Code that stores 4 July because that is the date of Independence Day treats that Friday as a normal working day.

Some countries move working days too. Russia publishes a government decree each autumn that rearranges the next year's days off, turning a Saturday into a working day and a Monday into a day off so that holidays join up with weekends. Those transfers are not holidays, so most holiday data leaves them out, and 31 December 2026 looks like an ordinary Thursday when it is in fact a day off.

Holidays are regional. Epiphany on 6 January is a day off in Bavaria and a working day in Berlin; Germany's national list does not contain it and the Bavarian one does. States, provinces and cantons elsewhere work the same way.

A holiday is also not always a day off. The data behind most services sorts days into public holidays, bank holidays, school holidays, optional days and observances. A public holiday usually closes government offices and banks, private employers may still open, and some days that are called holidays close nothing at all.

None of this produces an error. A country code and a date always yield an answer, and the answer always looks plausible.

What this endpoint does

A date is answered with day off or business day and the reason: a holiday's name, the weekend, or a transferred day together with the decree it comes from. Only days the source classifies as public holidays count; bank, school, optional and observance days are left out, and a list for a year says so.

Without region=, only nationwide holidays count. With an ISO 3166-2 code such as DE-BY, that region's own holidays are added, and a code from another country is refused. Where the source records an observed date, that date is used. Russian transfers are added by hand from each year's decree; until a year's decree is added, answers for that year say that only the Labour Code was applied. The weekend is Saturday and Sunday unless the country is known to differ, and weekend= overrides it.

Parameters

The whole path and query together are capped at 2048 bytes. Every parameter has the same meaning under /v1/holidays/{country}/{when}.

Examples

A holiday observed on a Friday

curl "https://agent-helper.org/holidays/us/2026-07-03"

day off
# US 2026-07-03 (fri)
# type: reference-data
# source: Nager.Date (with manual overrides)
# as-of: retrieved 2026-09-16T18:20:10Z
# reason: Independence Day
# weekend: sat,sun (built-in table (Saturday-Sunday unless known otherwise))
# license: https://github.com/nager/Nager.Date/blob/main/LICENSE.md

The holiday's own date, a Saturday

curl "https://agent-helper.org/holidays/us/2026-07-04"

day off
# US 2026-07-04 (sat)
# type: reference-data
# source: Nager.Date (with manual overrides)
# as-of: retrieved 2026-09-16T18:20:10Z
# reason: weekend (sat)
# weekend: sat,sun (built-in table (Saturday-Sunday unless known otherwise))
# license: https://github.com/nager/Nager.Date/blob/main/LICENSE.md

A transferred day off in Russia

curl "https://agent-helper.org/holidays/ru/2026-12-31"

day off
# RU 2026-12-31 (thu)
# type: reference-data
# source: Nager.Date (with manual overrides)
# as-of: retrieved 2026-09-16T18:20:10Z
# reason: Day off transferred from Sunday 4 January
# weekend: sat,sun (built-in table (Saturday-Sunday unless known otherwise))
# note: RU 2026: transfers of days off from Постановление Правительства РФ от 24.09.2025 N 1466 "О переносе выходных дней в 2026 году"; Трудовой кодекс РФ, ст. 112
# license: https://github.com/nager/Nager.Date/blob/main/LICENSE.md

A regional holiday

curl "https://agent-helper.org/holidays/de/2026-01-06?region=DE-BY"

day off
# DE 2026-01-06 (tue)
# type: reference-data
# source: Nager.Date (with manual overrides)
# as-of: retrieved 2026-09-16T18:20:10Z
# reason: Epiphany (Heilige Drei Könige)
# weekend: sat,sun (built-in table (Saturday-Sunday unless known otherwise))
# license: https://github.com/nager/Nager.Date/blob/main/LICENSE.md

A region of another country (error)

curl "https://agent-helper.org/holidays/de/2026-01-06?region=BY"

error: 400 bad parameter 'region'
parameter: region
problem: 'BY' is not an ISO 3166-2 code of DE
hint: e.g. DE-XX; see /ref/subdivisions/DE
[the rest of this error repeats the parameter list above]

Limits and provenance

Rate class static (cacheable data: documentation, reference tables, rates, holidays, feeds, current time): 600 requests a minute per address, bursts of 100; wider limits apply per network and per autonomous system. Current values: /limits.

Answers are marked # type: reference-data; successful ones are served with Cache-Control: public, max-age=3600.

Data comes from a copy refreshed on a schedule, never fetched on your request:

• Nager.Date (Nager.Date open source project), refreshed every week. Open-source project, no key required. Current licence of the hosted data to be confirmed before launch.

Freshness of each copy and full terms: /sources.

Related

• Time and dates: Current time, timezone conversion, date arithmetic, ISO weeks, cron and business days. Every answer carries the offset and the timezone rules it used.
• Reference tables: ISO country, currency and language codes, IANA timezones, TLDs, ports, media types, HTTP registries, CODATA constants and airports, each with its source.
• Currency exchange rates from central banks: Reference rates from the ECB and the Bank of Russia, no key. Two central banks publish different rates for one pair; both are right, and neither is for trading.

Every endpoint in this group

curl "https://agent-helper.org/holidays/de/2026"

curl "https://agent-helper.org/holidays/fr/next?after=2026-09-15"

curl "https://agent-helper.org/holidays/countries"