Schemas

Error

error

string · required

Human-readable error message.

Example: Invalid 'country'. Provide a 2-letter ISO-3166 alpha-2 code, e.g. US.

UpstreamError

error

string · required

Human-readable error message.

Example: Upstream holiday provider failed.

detail

string

Additional detail about the upstream failure.

Example: Nager.Date returned 500

Holiday

date

string · date · required

Calendar date of the holiday.

Example: 2026-07-03

localName

string · required

Holiday name in the country's local language.

Example: Independence Day

name

string · required

Holiday name in English.

Example: Independence Day

countryCode

string · required

ISO-3166 alpha-2 country code.

Example: US

fixed

boolean

Whether the holiday falls on a fixed calendar date.

Example: false

global

boolean

True for nationwide holidays; false for subdivision-only holidays.

Example: true

counties

array | null

ISO-3166-2 subdivision codes the holiday applies to, or null when nationwide.

Example: null

launchYear

integer | null

First year the holiday was observed, when known.

Example: null

types

string[]

Holiday type flags (e.g. Public, Bank, Optional).

Example: ["Public"]

Country

countryCode

string · required

ISO-3166 alpha-2 country code.

Example: US

name

string · required

English country name.

Example: United States

IsHolidayResponse

country

string · required

ISO-3166 alpha-2 country code that was checked.

Example: US

date

string · date · required

Date that was checked.

Example: 2026-07-03

is_holiday

boolean · required

Whether the date is a public holiday.

Example: true

object

The matching holiday record, or null when the date is not a public holiday.

Holiday

date

string · date · required

Calendar date of the holiday.

Example: 2026-07-03

localName

string · required

Holiday name in the country's local language.

Example: Independence Day

name

string · required

Holiday name in English.

Example: Independence Day

countryCode

string · required

ISO-3166 alpha-2 country code.

Example: US

fixed

boolean

Whether the holiday falls on a fixed calendar date.

Example: false

global

boolean

True for nationwide holidays; false for subdivision-only holidays.

Example: true

counties

array | null

ISO-3166-2 subdivision codes the holiday applies to, or null when nationwide.

Example: null

launchYear

integer | null

First year the holiday was observed, when known.

Example: null

types

string[]

Holiday type flags (e.g. Public, Bank, Optional).

Example: ["Public"]

IsHolidayResponse

country

string · required

ISO-3166 alpha-2 country code that was checked.

Example: US

date

string · date · required

Date that was checked.

Example: 2026-07-03

is_holiday

boolean · required

Whether the date is a public holiday.

Example: true

object

The matching holiday record, or null when the date is not a public holiday.