Holiday API

Public holidays by country, year, month, or day.

List published holidays and cultural observances for a country, then narrow the calendar to a month or day. Records include the date, name, regional scope, and the source calendar's substitute flag. The type field distinguishes official public holidays from cultural observance dates.

Collections always return a holidays array, including every record when multiple holidays share a date. A covered period with no matches returns an empty array. An unavailable year returns 404 with the available range. Future dates come from official publications or finite, independently reviewed current rules; they do not claim a future annual publication.

Year

GET

api.parseapi.com/holiday/{country}/{year}

Year collection, for example /holiday/US/2026

Explore

GET

api.parseapi.com/holiday/{country}

Current year, with optional year, month, and day query filters

Explore

Parameters 7

countrystring · path · required

ISO 3166-1 alpha-2 country code

Pattern: ^[A-Za-z]{2}$

typestring · query · optional

Select public or observance. Omit to retain both categories and the existing public-first single-date choice. A covered category miss returns an empty array or holiday: null; a missing calendar remains 404. edition plus observance returns 400. Unknown or repeated selectors return 400. Frozen 1.0.0 remains unchanged.

Values: public, observance

yearinteger · query · optional

Four-digit available year; defaults to the current UTC year. Must match a path year when supplied.

Range: 1 to 9999

monthinteger · query · optional

Collection month. Must match a path month when supplied.

Range: 1 to 12

dayinteger · query · optional

Collection day. Requires month and a real calendar date.

Range: 1 to 31

regionstring · query · optional

Reviewed subdivision suffix such as NSW or matching full code AU-NSW. Includes nationwide plus matching regional dates outside the US. Reviewed US states select their independent employee calendar, plus current countrywide observances when requested. Case-insensitive; unsupported or wrong-country regions return 400.

Pattern: ^(?:[A-Za-z]{2}-)?[A-Za-z0-9]{1,6}$

editionstring · query · optional

One retained public-calendar edition for this country and year. Pins frozen public records, excludes observances, and returns edition. Unknown edition 404, wrong country/year 400, invalid archive 503. Does not establish live availability.

Pattern: ^[a-f0-9]{64}$

Omit year for the current UTC year. Add month to narrow the collection.

curl "https://api.parseapi.com/holiday/US/2026" \
  -H "X-API-Key: YOUR_API_KEY" \
  -H "Parse-Version: 2.0.0"

Run on your server with a secret key. Calling from a browser or app?

Example response

{
  "country": "US",
  "year": 2026,
  "holidays": [
    {
      "date": "2026-01-01",
      "name": "New Year's Day",
      "name_local": null,
      "type": "public",
      "regions": null,
      "substitute": false
    },
    {
      "date": "2026-01-19",
      "name": "Birthday of Martin Luther King, Jr.",
      "name_local": null,
      "type": "public",
      "regions": null,
      "substitute": false
    },
    {
      "date": "2026-02-14",
      "name": "Valentine's Day",
      "name_local": null,
      "type": "observance",
      "regions": null,
      "substitute": false
    },
    {
      "date": "2026-02-16",
      "name": "Washington's Birthday",
      "name_local": null,
      "type": "public",
      "regions": null,
      "substitute": false
    },
    {
      "date": "2026-03-17",
      "name": "St. Patrick's Day",
      "name_local": null,
      "type": "observance",
      "regions": null,
      "substitute": false
    },
    {
      "date": "2026-04-03",
      "name": "Good Friday",
      "name_local": null,
      "type": "observance",
      "regions": null,
      "substitute": false
    },
    {
      "date": "2026-04-05",
      "name": "Easter Sunday",
      "name_local": null,
      "type": "observance",
      "regions": null,
      "substitute": false
    },
    {
      "date": "2026-05-05",
      "name": "Cinco de Mayo",
      "name_local": null,
      "type": "observance",
      "regions": null,
      "substitute": false
    },
    {
      "date": "2026-05-10",
      "name": "Mother's Day",
      "name_local": null,
      "type": "observance",
      "regions": null,
      "substitute": false
    },
    {
      "date": "2026-05-25",
      "name": "Memorial Day",
      "name_local": null,
      "type": "public",
      "regions": null,
      "substitute": false
    },
    {
      "date": "2026-06-19",
      "name": "Juneteenth National Independence Day",
      "name_local": null,
      "type": "public",
      "regions": null,
      "substitute": false
    },
    {
      "date": "2026-06-21",
      "name": "Father's Day",
      "name_local": null,
      "type": "observance",
      "regions": null,
      "substitute": false
    },
    {
      "date": "2026-07-03",
      "name": "Independence Day",
      "name_local": null,
      "type": "public",
      "regions": null,
      "substitute": true
    },
    {
      "date": "2026-09-07",
      "name": "Labor Day",
      "name_local": null,
      "type": "public",
      "regions": null,
      "substitute": false
    },
    {
      "date": "2026-10-12",
      "name": "Columbus Day",
      "name_local": null,
      "type": "public",
      "regions": null,
      "substitute": false
    },
    {
      "date": "2026-10-31",
      "name": "Halloween",
      "name_local": null,
      "type": "observance",
      "regions": null,
      "substitute": false
    },
    {
      "date": "2026-11-11",
      "name": "Veterans Day",
      "name_local": null,
      "type": "public",
      "regions": null,
      "substitute": false
    },
    {
      "date": "2026-11-26",
      "name": "Thanksgiving Day",
      "name_local": null,
      "type": "public",
      "regions": null,
      "substitute": false
    },
    {
      "date": "2026-11-27",
      "name": "Black Friday",
      "name_local": null,
      "type": "observance",
      "regions": null,
      "substitute": false
    },
    {
      "date": "2026-12-24",
      "name": "Christmas Eve",
      "name_local": null,
      "type": "observance",
      "regions": null,
      "substitute": false
    },
    {
      "date": "2026-12-25",
      "name": "Christmas Day",
      "name_local": null,
      "type": "public",
      "regions": null,
      "substitute": false
    },
    {
      "date": "2026-12-31",
      "name": "New Year's Eve",
      "name_local": null,
      "type": "observance",
      "regions": null,
      "substitute": false
    }
  ]
}

Response fields

countrystring: ISO2 country code
yearinteger: Year returned
monthinteger: Selected month, present on month and day collections
dayinteger: Selected day of month, present on day collections
holidaysarray: Every matching holiday and observance, including multiple names on one date. Empty array for a covered period with no matches
holidays[].datestring: Date, YYYY-MM-DD
holidays[].namestring: Official name, English or the official translation (France stays French)
holidays[].name_localstring or null: Native form when it differs (Japan kanji, Hong Kong and Taiwan Chinese), null otherwise
holidays[].typestring: public for an officially designated holiday, observance for cultural dates (Halloween, Black Friday)
holidays[].regionsarray or null: Subdivision codes where this record applies (GB: ENG, WLS, SCT, NIR). Null means country-wide within the calendar’s declared scope; it does not establish workplace closure
holidays[].substituteboolean: Source calendar replacement or in-lieu flag. It does not establish the original occasion; reviewed actual/observed relationships are available in calendar Deep when known
editionstring: Only with a requested archive pin: the exact public calendar edition. Archived rows do not establish current live availability

Month

GET

api.parseapi.com/holiday/{country}/{year}-{month}

Month collection. Same result as ?year=2026&month=12

Explore

curl "https://api.parseapi.com/holiday/US/2026-12" \
  -H "X-API-Key: YOUR_API_KEY" \
  -H "Parse-Version: 2.0.0"

Run on your server with a secret key. Calling from a browser or app?

Example response

{
  "country": "US",
  "year": 2026,
  "month": 12,
  "holidays": [
    {
      "date": "2026-12-24",
      "name": "Christmas Eve",
      "name_local": null,
      "type": "observance",
      "regions": null,
      "substitute": false
    },
    {
      "date": "2026-12-25",
      "name": "Christmas Day",
      "name_local": null,
      "type": "public",
      "regions": null,
      "substitute": false
    },
    {
      "date": "2026-12-31",
      "name": "New Year's Eve",
      "name_local": null,
      "type": "observance",
      "regions": null,
      "substitute": false
    }
  ]
}

Day collection

Use year, month, and day query filters for every holiday on a date. Day requires month. You can also add day to a month path.

curl "https://api.parseapi.com/holiday/US?year=2026&month=12&day=25" \
  -H "X-API-Key: YOUR_API_KEY" \
  -H "Parse-Version: 2.0.0"

Run on your server with a secret key. Calling from a browser or app?

Example response

{
  "country": "US",
  "year": 2026,
  "month": 12,
  "day": 25,
  "holidays": [
    {
      "date": "2026-12-25",
      "name": "Christmas Day",
      "name_local": null,
      "type": "public",
      "regions": null,
      "substitute": false
    }
  ]
}

Use YYYY, YYYY-MM, or YYYY-MM-DD in paths. Months and days in paths need two digits. Invalid dates and conflicting path and query values return 400 with guidance. Matching values are allowed.

One date

The full date path keeps its existing response. holiday is one matching record, or null for a covered date with no match. A public holiday takes priority when the date has multiple records. Use the day collection to keep every name. A missing holiday does not establish a working day.

GET

api.parseapi.com/holiday/{country}/{date}

One date, YYYY-MM-DD. The holiday object, or holiday: null

Explore

Parameters 8

countrystring · path · required

ISO 3166-1 alpha-2 country code

Pattern: ^[A-Za-z]{2}$

datestring · path · required

YYYY, YYYY-MM, or YYYY-MM-DD. Path months and days require two digits. Full dates must be real calendar dates.

Pattern: ^\d{4}(?:-\d{2}){0,2}$

typestring · query · optional

Values: public, observance

yearinteger · query · optional

Four-digit available year; defaults to the current UTC year. Must match a path year when supplied.

Range: 1 to 9999

monthinteger · query · optional

Collection month. Must match a path month when supplied.

Range: 1 to 12

dayinteger · query · optional

Collection day. Requires month and a real calendar date.

Range: 1 to 31

regionstring · query · optional

Pattern: ^(?:[A-Za-z]{2}-)?[A-Za-z0-9]{1,6}$

editionstring · query · optional

Pattern: ^[a-f0-9]{64}$

Example

SDK quickstart

import { parseAPI } from '@parseapi/sdk';

const parse = parseAPI("YOUR_API_KEY");
const result = await parse.holiday.date("US", "2026-12-25");
console.log(result);

Run on your server with a secret key. Calling from a browser or app?

Example response

{
  "country": "US",
  "date": "2026-12-25",
  "holiday": {
    "date": "2026-12-25",
    "name": "Christmas Day",
    "name_local": null,
    "type": "public",
    "regions": null,
    "substitute": false
  }
}

Response fields

countrystring: ISO2 country code
datestring: Date checked
holidayobject or null: The holiday on that date (same shape as holidays[]), or null
editionstring: Only with a requested archive pin: the exact public calendar edition. Archived rows do not establish current live availability

Native names

Japan pairs the official English name with kanji in name_local, back to 1955.

SDK quickstart

import { parseAPI } from '@parseapi/sdk';

const parse = parseAPI("YOUR_API_KEY");
const result = await parse.holiday("JP", { year: 1955 });
console.log(result);

Run on your server with a secret key. Calling from a browser or app?

Example response

{
  "country": "JP",
  "year": 1955,
  "holidays": [
    {
      "date": "1955-01-01",
      "name": "New Year's Day",
      "name_local": "元日",
      "type": "public",
      "regions": null,
      "substitute": false
    },
    {
      "date": "1955-01-15",
      "name": "Coming of Age Day",
      "name_local": "成人の日",
      "type": "public",
      "regions": null,
      "substitute": false
    },
    {
      "date": "1955-03-03",
      "name": "Hinamatsuri",
      "name_local": "ひな祭り",
      "type": "observance",
      "regions": null,
      "substitute": false
    },
    {
      "date": "1955-03-21",
      "name": "Vernal Equinox Day",
      "name_local": "春分の日",
      "type": "public",
      "regions": null,
      "substitute": false
    },
    {
      "date": "1955-04-29",
      "name": "Emperor's Birthday",
      "name_local": "天皇誕生日",
      "type": "public",
      "regions": null,
      "substitute": false
    },
    {
      "date": "1955-05-03",
      "name": "Constitution Memorial Day",
      "name_local": "憲法記念日",
      "type": "public",
      "regions": null,
      "substitute": false
    },
    {
      "date": "1955-05-05",
      "name": "Children's Day",
      "name_local": "こどもの日",
      "type": "public",
      "regions": null,
      "substitute": false
    },
    {
      "date": "1955-07-07",
      "name": "Tanabata",
      "name_local": "七夕",
      "type": "observance",
      "regions": null,
      "substitute": false
    },
    {
      "date": "1955-08-15",
      "name": "Obon",
      "name_local": "お盆",
      "type": "observance",
      "regions": null,
      "substitute": false
    },
    {
      "date": "1955-09-24",
      "name": "Autumnal Equinox Day",
      "name_local": "秋分の日",
      "type": "public",
      "regions": null,
      "substitute": false
    },
    {
      "date": "1955-11-03",
      "name": "Culture Day",
      "name_local": "文化の日",
      "type": "public",
      "regions": null,
      "substitute": false
    },
    {
      "date": "1955-11-15",
      "name": "Shichi-Go-San",
      "name_local": "七五三",
      "type": "observance",
      "regions": null,
      "substitute": false
    },
    {
      "date": "1955-11-23",
      "name": "Labor Thanksgiving Day",
      "name_local": "勤労感謝の日",
      "type": "public",
      "regions": null,
      "substitute": false
    },
    {
      "date": "1955-12-24",
      "name": "Christmas Eve",
      "name_local": "クリスマスイブ",
      "type": "observance",
      "regions": null,
      "substitute": false
    },
    {
      "date": "1955-12-25",
      "name": "Christmas",
      "name_local": "クリスマス",
      "type": "observance",
      "regions": null,
      "substitute": false
    },
    {
      "date": "1955-12-31",
      "name": "New Year's Eve",
      "name_local": "大晦日",
      "type": "observance",
      "regions": null,
      "substitute": false
    }
  ]
}

Coverage, downloads and working schedules

Choose a type or region

Add type=public or type=observance to the ordinary collection or date route. Omitting type keeps both categories and the public-first single-date choice. A covered category with no match returns an empty collection or null; an unavailable year remains 404. Use region=NSW or region=AU-NSW for nationwide and matching regional dates. For the US, region selects a separate reviewed state scope; omitting it keeps federal employee dates. State dates do not inherit federal closures. Unsupported or wrong-country regions return 400.

Check coverage

GET

api.parseapi.com/holiday/{country}/coverage

Available years and reviewed scope. Add year to check one year

Explore

Parameters 2

countrystring · path · required

ISO 3166-1 alpha-2 country code

Pattern: ^[A-Za-z]{2}$

yearinteger · query · optional

Check this four-digit year. Omit to inspect all actual serving and recorded candidate years.

Range: 1 to 9999

GET /holiday/AU/coverage?year=2027

A missing year returns 200 with available: false here; requesting its dates returns 404. A matched year supplies its edition, scope, completeness and regions. Unknown annual date review and material source alerts remain explicit. Failed or changed sources do not replace retained dates.

Response fields

countrystring: ISO2 country code
namestring: Country or territory name
yearinteger: With year: the selected year
availableboolean: Whether public records are served for the selected year
verificationstring: matched, unverified or unavailable. Availability alone does not establish reviewed dates
editionstring: For a matched year: its exact public calendar edition
scopestring: Declared calendar scope and limitations
completenessstring: reviewed_scope or partial, within the declared scope
regionsarray: Subdivision suffixes represented in this year
pendingarray: Recorded unresolved items; omitted when empty
yearsarray: Without year: each year and its availability and verification

Read or save a calendar

GET

api.parseapi.com/holiday/{country}/calendar

Reviewed public calendar. Explicit year required

Explore

Parameters 6

countrystring · path · required

ISO 3166-1 alpha-2 country code

Pattern: ^[A-Za-z]{2}$

yearinteger · query · required

Explicit four-digit year. Unavailable years remain 404.

Range: 1 to 9999

deepboolean · query · optional

Add reviewed actual/observed relationships and their citations when known.

formatstring · query · optional

json returns the complete calendar resource. ics and csv download immutable snapshots, not live subscriptions.

Default: json

Values: json, ics, csv

editionstring · query · optional

One retained public-calendar fingerprint for the exact country/year. Reads its complete frozen public edition. Unknown edition 404, country/year mismatch 400, invalid archive 503.

Pattern: ^[a-f0-9]{64}$

regionstring · query · optional

Selects an independent US state edition, including JSON; its edition pin requires the matching state. Other countries accept region for downloads only. Portugal ICS defaults to national dates and US ICS to federal employee dates. Other regional ICS requires a region. CSV can retain the full selected edition or filter a region.

Pattern: ^(?:[A-Za-z]{2}-)?[A-Za-z0-9]{1,6}$

GET /holiday/AU/calendar?year=2027
GET /holiday/AU/calendar?year=2027&deep=true

The complete holidays array uses the same six holiday fields as an ordinary lookup. Calendar scope, completeness and edition qualify the returned dates. Unknown annual date review remains explicit. Pending dates appear only when recorded. Optional deep=true adds actual/observed date relationships and their citations only when independently reviewed. Unknown relationships do not produce placeholder fields.

GET

api.parseapi.com/holiday/{country}/calendar?format=ics

All-day iCalendar snapshot of a reviewed calendar scope

Explore

Parameters 6

countrystring · path · required

ISO 3166-1 alpha-2 country code

Pattern: ^[A-Za-z]{2}$

yearinteger · query · required

Explicit four-digit year. Unavailable years remain 404.

Range: 1 to 9999

deepboolean · query · optional

Add reviewed actual/observed relationships and their citations when known.

formatstring · query · optional

json returns the complete calendar resource. ics and csv download immutable snapshots, not live subscriptions.

Default: json

Values: json, ics, csv

editionstring · query · optional

One retained public-calendar fingerprint for the exact country/year. Reads its complete frozen public edition. Unknown edition 404, country/year mismatch 400, invalid archive 503.

Pattern: ^[a-f0-9]{64}$

regionstring · query · optional

Pattern: ^(?:[A-Za-z]{2}-)?[A-Za-z0-9]{1,6}$

GET

api.parseapi.com/holiday/{country}/calendar?format=csv

CSV with literal civil dates and reviewed scope

Explore

Parameters 6

countrystring · path · required

ISO 3166-1 alpha-2 country code

Pattern: ^[A-Za-z]{2}$

yearinteger · query · required

Explicit four-digit year. Unavailable years remain 404.

Range: 1 to 9999

deepboolean · query · optional

Add reviewed actual/observed relationships and their citations when known.

formatstring · query · optional

json returns the complete calendar resource. ics and csv download immutable snapshots, not live subscriptions.

Default: json

Values: json, ics, csv

editionstring · query · optional

One retained public-calendar fingerprint for the exact country/year. Reads its complete frozen public edition. Unknown edition 404, country/year mismatch 400, invalid archive 503.

Pattern: ^[a-f0-9]{64}$

regionstring · query · optional

Pattern: ^(?:[A-Za-z]{2}-)?[A-Za-z0-9]{1,6}$

GET /holiday/AU/calendar?year=2027&format=ics&region=NSW
GET /holiday/AU/calendar?year=2027&format=csv&region=NSW

ICS uses all-day civil dates with exclusive next-date ends. For most countries, a region includes national and matching regional dates. US region selects an independent state edition for JSON and downloads; a state edition pin requires that same region. iCalendar defaults to federal employee dates for the US and national dates for Portugal. Other regional iCalendar downloads require a region. CSV can omit region to keep the full selected edition. Downloads retain their edition, scope and annual date verification and return Content-Disposition. They are edition snapshots, not live subscriptions. Fetch a newer edition to receive corrections.

Pass edition to repeat the retained public dates, archived scope and original review. Current qualifications may be newer. Ordinary collection/date pins return the edition alongside their existing shape. Pins exclude observances. An unknown edition returns 404; a wrong country or year returns 400. Omit edition for current dates and qualifications.

List a date window

GET

api.parseapi.com/holiday/{country}/range

Inclusive from and to, across up to 731 civil dates

Explore

Parameters 6

countrystring · path · required

ISO 3166-1 alpha-2 country code

Pattern: ^[A-Za-z]{2}$

fromstring · query · required

Real inclusive civil start date, chosen by the caller.

tostring · query · required

Real inclusive civil end date; at most 731 dates including both bounds.

typestring · query · optional

Current defaults to public plus observance. Select one category. Pinned editions include public only and reject type=observance.

Values: public, observance

regionstring · query · optional

Nationwide plus matching regional rows outside the US. A reviewed US state selects its independent annual public calendar. Current countrywide observances are included when requested. The region must be represented in every reached annual public calendar; unsupported annual regional scope returns 400.

Pattern: ^(?:[A-Za-z]{2}-)?[A-Za-z0-9]{1,6}$

editionstring · query · optional

Exactly one distinct public-calendar fingerprint for every reached year, at most three, in any order. Pinned lists include public only and never borrow current observances. Missing/wrong year 400, unknown edition 404, invalid archive 503.

Length: 0 to 194 characters

Pattern: ^[a-f0-9]{64}(?:,[a-f0-9]{64}){0,2}$

GET /holiday/AU/range?from=2026-12-25&to=2027-01-03&region=NSW&type=public

Every matching record remains in holidays, including separate names sharing a date. calendars identifies the edition and scope of every reached year. Current windows include public holidays and curated observances unless type selects one. An archived window requires one public edition per reached year and contains public holidays only. Missing any required year returns 404; unmatched review evidence returns 503. There is no partial result or silent truncation.

Count working days

GET

api.parseapi.com/holiday/{country}/workdays

Inclusive interval with an explicit working week

Explore

Parameters 11

countrystring · path · required

ISO 3166-1 alpha-2 country code

Pattern: ^[A-Za-z]{2}$

fromstring · query · required

First date, included in the result.

tostring · query · required

Last date, included in the result. Must be on or after from and at most 365 days later.

regionstring · query · optional

Reviewed subdivision suffix or matching full code. Required for regional calendars except Portugal and the US: omit for Portugal national holidays or US federal employee holidays. PT-20 selects Azores; PT-30 Madeira. Reviewed US states select their independent employee calendar and edition.

Pattern: ^(?:[A-Za-z]{2}-)?[A-Za-z0-9]{1,6}$

weekendstring · query · required

Explicit comma-separated weekday digits: 0 is Sunday and 6 is Saturday. Use none for no weekend days. No country default is supplied.

Pattern: ^(?:none|[0-6](?:,[0-6])*)$

working_datesstring · query · optional

Up to 50 comma-separated YYYY-MM-DD dates within the requested interval to treat as working.

closed_datesstring · query · optional

Up to 50 comma-separated YYYY-MM-DD dates within the requested interval to treat as closed. A date cannot appear in both override lists.

work_profilestring · query · optional

Explicit official profile: tw-government-office for TW2027 government administrative offices (published per-date status replaces the supplied weekend), cn-national-adjustments for CN2026 national breaks/make-up workdays, ru-five-day-adjustments for RU2027 five-day national adjustments, or by-five-day-adjustments for BY2027 prescribed five-day adjustments (CN/RU/BY require weekend=0,6). RU2027 and BY2027 scheduling require their profiles; missing selection returns 400. BY2027 makes May 8 working and May 10 a rest day, excluding employer alternative Saturdays, six-day and shift schedules. Every requested year must have a matching profile. No default; wrong country/year/weekend 400, changed bound calendar edition or scope 503. Caller date overrides take precedence.

Values: tw-government-office, cn-national-adjustments, ru-five-day-adjustments, by-five-day-adjustments

work_profile_editionstring · query · optional

Exact retained lowercase SHA-256 official work-profile fingerprint. Requires work_profile and a single requested year. Reads that immutable profile; unknown fingerprint 404 with no current fallback, wrong profile/year 400, invalid retained evidence 503. Pin public calendar edition too to reproduce the full calculation. Without this selector, profile ID selects the current reviewed profile.

Pattern: ^[a-f0-9]{64}$

editionstring · query · optional

Comma-separated retained public-calendar fingerprints, exactly one for each requested year and at most two. Explicitly selects archived calendars instead of current serving records. Prepared archive origins do not establish live availability. Unknown fingerprint 404; wrong country, year or count 400; invalid archive 503.

Pattern: ^[a-f0-9]{64}(?:,[a-f0-9]{64})?$

deepboolean · query · optional

Add the explanation for each considered civil date in deep.days. Omitted by default.

GET /holiday/AU/workdays?from=2027-01-01&to=2027-01-31&region=NSW&weekend=0,6

Supply a range of up to 366 dates and your weekend policy. weekend=0,6 means Sunday and Saturday; weekend=none means no weekend dates. The US uses federal employee holidays unless a reviewed state is selected. Other regional calendars require a region. Portugal retains its national statutory baseline without region; select region=20 for Azores or region=30 for Madeira holidays. Applicable public holidays close dates; observances do not. The ordinary response completes the count with workdays, the selected policy and compact calendar references. Add deep=true for deep.days, each considered date and its reason.

Response fields

countrystring: ISO2 country code
fromstring: First date, included
tostring: Last date, included; at most 366 dates
regionstring or null: Selected subdivision suffix or null
policy.weekendarray: Explicit weekday numbers, 0 Sunday through 6 Saturday
policy.working_datesarray: Caller overrides; omitted when empty
policy.closed_datesarray: Caller closures; omitted when empty
policy.work_profileobject: Only when selected: official profile ID, declared scope and retained annual profile editions
workdaysinteger: Working-day count under the supplied schedule
calendarsarray: Every used year’s edition, scope, completeness and review date; unresolved relevant dates stop the calculation
deep.daysarray: Only with deep=true: each date, working flag and reason

Find a working date

GET

api.parseapi.com/holiday/{country}/business-date

Add or subtract working days from a start date

Explore

Parameters 12

countrystring · path · required

ISO 3166-1 alpha-2 country code

Pattern: ^[A-Za-z]{2}$

start_datestring · query · required

Real civil start date. The default excludes this date from the count.

business_daysinteger · query · required

Signed integer offset. Use a negative value to count backward, or zero to retain the start.

Range: -366 to 366

include_start_dateboolean · query · optional

Count the start as the first date only when it is working. The default excludes it. Zero always leaves the start unchanged.

Default: false

regionstring · query · optional

Pattern: ^(?:[A-Za-z]{2}-)?[A-Za-z0-9]{1,6}$

weekendstring · query · required

Explicit comma-separated weekday digits: 0 is Sunday and 6 is Saturday. Use none for no weekend days. No country default is supplied.

Pattern: ^(?:none|[0-6](?:,[0-6])*)$

working_datesstring · query · optional

Up to 50 comma-separated YYYY-MM-DD caller overrides in the selected direction, within 732 calendar days of start_date. A date cannot appear in both override lists.

closed_datesstring · query · optional

Up to 50 comma-separated YYYY-MM-DD caller overrides in the selected direction, within 732 calendar days of start_date. A date cannot appear in both override lists.

work_profilestring · query · optional

Values: tw-government-office, cn-national-adjustments, ru-five-day-adjustments, by-five-day-adjustments

work_profile_editionstring · query · optional

Pattern: ^[a-f0-9]{64}$

deepboolean · query · optional

Add the explanation for each considered civil date in deep.days. Omitted by default.

editionstring · query · optional

Exactly one retained public-calendar fingerprint per reached year, at most four. A missing or extra year pin returns 400. Unknown editions return 404 and invalid archives return 503. Pinning never falls back to current calendars.

Length: 0 to 259 characters

Pattern: ^[a-f0-9]{64}(?:,[a-f0-9]{64}){0,3}$

GET /holiday/US/business-date?start_date=2027-01-05&business_days=-1&weekend=0,6

The signed count accepts −366 through 366. Negative numbers count backward. The start is excluded unless include_start_date=true and it is working. Zero preserves the start after checking its calendar. The walk is bounded to 732 calendar days. The response returns the reached date; optional Deep explains each considered date and whether it counted.

Both schedule routes accept up to 50 explicit working_dates and closed_dates each. Overrides take precedence; contradictory overrides return 400. Official profiles are selected explicitly: Taiwan government offices in 2027 replace weekend classification with the published daily schedule, while China national adjustments in 2026 apply announced breaks and make-up workdays to an explicit Saturday/Sunday weekend. Their declared scope excludes employer-specific rules. Pin a profile with its returned work_profile_edition and calendar edition. Missing years return 404; unverified or relevant unresolved dates return 503. Uruguay includes designated working holidays, so these calculations return 503 until a reviewed closure policy is available. Its date and calendar lookups remain available.

Replay corrections

GET

api.parseapi.com/holiday/{country}/events

Retained corrections, paged by event ID

Explore

Parameters 4

countrystring · path · required

ISO 3166-1 alpha-2 country code

Pattern: ^[A-Za-z]{2}$

yearinteger · query · optional

Optional historical event year. An empty result means no retained events for that year, not an available holiday calendar.

Range: 1000 to 9999

afterstring · query · optional

Exact last-seen event ID in the selected country and optional year. Unknown ID returns 404 and mismatched scope 400.

Pattern: ^hevt_[a-f0-9]{64}$

limitinteger · query · optional

Maximum events in this page. Continue with next_cursor while has_more is true.

Default: 20

Range: 1 to 100

Events contain immutable IDs, exact before/after rows, previous/current editions and first-retained created Unix seconds. This records when a correction entered history, separately from an authority’s publication date. Optional year filters the feed. Limit is 1–100, default 20. While has_more is true, continue with after=next_cursor. Store the last event ID to resume polling. Unknown cursors return 404 and scope mismatches return 400.

History declares its retained_since boundary and complete: false. Earlier transitions are absent. An empty event page does not establish calendar availability. This is polling and replay.

Partial planning announcements

GET

api.parseapi.com/holiday/{country}/planning

Explicit year. Official announcements before a complete calendar

Explore

Parameters 2

countrystring · path · required

ISO 3166-1 alpha-2 country code

Pattern: ^[A-Za-z]{2}$

yearinteger · query · required

Explicit four-digit year for a retained official planning set. No default year is inferred.

Range: 1 to 9999

GET /holiday/PH/planning?year=2027

Each announced date adds confirmation: confirmed or provisional. The set keeps complete: false, declared scope and unresolved items. An unlisted date cannot be assumed working. Planning announcements cannot support workday calculations or fill an unavailable ordinary calendar. Missing planning data returns 404.

Response fields

countrystring: ISO2 country code
yearinteger: Announcement year
completeboolean: false. An unlisted date cannot be assumed working
scopestring: Official announcement scope and limitations
pendingarray: Unresolved holidays or dates
holidaysarray: Six ordinary holiday fields plus confirmation
holidays[].confirmationstring: confirmed or provisional, without asserting full-calendar completeness
source_alertsarray: Only when relevant: a changed or failed source check

Build with Holiday

All tutorials →

Questions? Email

Holiday API

Year#

Month#

Day collection#

One date#

Native names#

Choose a type or region#

Check coverage#

Read or save a calendar#

List a date window#

Count working days#

Find a working date#

Replay corrections#

Partial planning announcements#

Build with Holiday

Year

Month

Day collection

One date

Native names

Choose a type or region

Check coverage

Read or save a calendar

List a date window

Count working days

Find a working date

Replay corrections

Partial planning announcements