holidays/list

All public holidays for a given country and year, with localized names.

Free / no pricing configured

What it does

Returns every public holiday for a country in a given year as date and name pairs. Optionally scoped to a subdivision (state/province) and localized to a language.

Primary use cases

Building a holiday calendar for scheduling or staffing.
Computing working days between two dates.
Localizing an application's calendar to a specific country.

Good to know

Country codes are ISO 3166-1 alpha-2 (e.g. US, GB, DE). year defaults to the current year. Some holidays are regional; pass subdivision (ISO 3166-2, e.g. CA for California) to include them. Computed locally, so there is no upstream rate limit.

Parameters

yearintegeroptional

Four-digit year. Defaults to the current year.

countrystringrequired

ISO 3166-1 alpha-2 country code (e.g. US, GB, DE).

languagestringoptional

Optional language code for localized holiday names (e.g. de, fr).

subdivisionstringoptional

Optional ISO 3166-2 subdivision code for regional holidays (e.g. CA, TX, BY).