Holiday api

Simple api used for tracking holidays

Endpoints

Fetching is done via GET /api/v1/holidays endpoint

That endpoint accepts a list of required and optional parameters

Required parameters

country

• determines for which country holidays are fetched, uses ISO 3166-1 Alpha-2 codes more info here
• eg. country=US

Optional parameters

year

• returns only holidays for given year
• eg. year=2023
• only used if no more important parameters are defined

date

• returns only holidays for given date
• date must be formatted in ISO 8601 format more info here
• eg. date=2021-12-25
• if defined year and rangeStart|rangeEnd parameters are ignored

rangeStart|rangeEnd

• returns holidays in given range with both ends being inclusive
• if either limit isn't defined it is assumed to be up to or all from given limit (if rangeStart isn't defined all holidays before rangeEnd are returned and vice-verse)
• dates must be formatted in ISO 8601 format more info here
• eg. rangeStart=2021-12-25&rangeEnd=2023-01-23, rangeStart=2023-01-20
• if defined year parameter is ignored

stateHoliday

• if set true only holidays that are tagged as state holidays are returned, similar for if set false, if not set all holidays are returned
• eg. stateHoliday=true, stateHoliday=false

religiousHoliday

• if set true only holidays that are tagged as religious holidays are returned, similar for if set false, if not set all holidays are returned
• eg. religiousHoliday=true, religiousHoliday=false

Paging

pageSize

• returns at most pageSize number of holidays
• eg. pageSize=20
• only applied if page is defined as well, by default set to 20

page

• returns nth page of holidays, paging starts at 0
• eg. page=0

Response

By default, responses are returned as a json array

{
  holidays: [{
    id: string;
    date: string(ISO 8601);
    name: string;
    description: string;
    isStateHoliday: boolean;
    isReligiousHoliday: boolean;
  },...]
}

eg.

{
  "holidays": [{
      "id": "74a2a769-abf2-45d4-bdc4-442bbcc89138",
      "date": "2023-12-25",
      "name": "Christmas",
      "description": "TBD",
      "isStateHoliday": true,
      "isReligiousHoliday": true
  }]
}

But can be returned as XML or CSV by setting appropriate Accept header (application/xml, text/xml or text/csv)

XML Response

<?xml version="1.0" encoding="UTF-8" standalone="yes" ?>
<Holidays>
    <Holiday id="74a2a769-abf2-45d4-bdc4-442bbcc89138" date="2023-12-25" isReligious="true" isState="true">
        <name>Christmas</name>
        <description>TBD</description>
    </Holiday>
</Holidays>

CSV Response

id,date,name,description,is_state_holiday,is_religious_holiday
74a2a769-abf2-45d4-bdc4-442bbcc89138,2023-12-25,Christmas,TBD,true,true