List holidays

Introduction

Retrieves a list public holidays and observances for countries, states and provinces.

Rate limiting and throttling

We're here to support the speed of your business - there are no rate limits in place.

Usage

To list available countries, you'll need to make a request to GET /list endpoint. You can alter received response by using filters as well as premium filters.

JavaScript
PHP
Go

const axios = require('axios');

axios.get('https://api.getfestivo.com/v3/public-holidays/list', {
    params: {
      api_key: "XXXXXX-XXXX-XXXX-XXXX-XXXXXXXXX",
      country: "US",
      year: 2024
    }
  })
  .then(function (response) {
    // handle success
    console.log(response)
  })
  .catch(function (error) {
    // handle error
    console.log(error)
  })
  .then(function () {
    // always executed
  })

$ch = curl_init();
$data = http_build_query(array(
  "api_key" => "XXXXXX-XXXX-XXXX-XXXX-XXXXXXXXX",
  "country" => "US",
  "year" => 2024
));
$getUrl = "https://api.getfestivo.com/public-holidays/v3/list?" . $data;
curl_setopt($ch, CURLOPT_SSL_VERIFYPEER, FALSE);
curl_setopt($ch, CURLOPT_FOLLOWLOCATION, TRUE);
curl_setopt($ch, CURLOPT_RETURNTRANSFER, TRUE);
curl_setopt($ch, CURLOPT_URL, $getUrl);
curl_setopt($ch, CURLOPT_TIMEOUT, 5);

$response = curl_exec($ch);

if(curl_error($ch)){
  echo 'Request Error:' . curl_error($ch);
} else {
  echo $response;
}

curl_close($ch);

import (
  "net/http"
  "os"
)

req, err := http.NewRequest("GET", "https://api.getfestivo.com/public-holidays/v3/list", nil)
if err != nil {
  // handle fatal error
  os.Exit(1)
}

q := url.Values{}
q.Add("api_key", "XXXXXX-XXXX-XXXX-XXXX-XXXXXXXXX")
q.Add("country", "US")
q.Add("year", "2024")

req.URL.RawQuery = q.Encode()

resp, err := client.Do(req)
if err != nil {
  // handle error
}

defer resp.Body.Close()
body, err := io.ReadAll(resp.Body)

Filters

In GET query you are able to append more parameters. Some of them are required some of them are optional, but each of them alter received list of holidays a bit. Please make yourself comfortable with the list below before you start using our Public Holidays API.

Parameter	Required	Description	Type	Example
country	yes	ISO 3166-1 alpha-2 country code from Countries section.	string	US
year	yes	4-digit year	int	2022
month	no	1 or 2 digit month identifier (MM or M)	int	06
day	no	1 or 2 digit day identifier (DD or D)	int	23
public	no	Return only public holidays	bool	1

Premium filters

caution

This functionality is only available in Starter, Business and Enterprise plans.

Depending on your plan, there are some additional filters available, allowing you to return holidays & observances in a specific language, within a dates range, calculating observance dates for specific timezones, as well as allowing to filter by subdivisions.

Parameter	Required	Description	Type	Example
before	no	Return only holidays before given date (default: `0`)	bool	1
after	no	Return only holidays after given date (default: `0`)	bool	1
format	no	Define return data format (available: `json`, `xml`)	string	json
timezone	no	Convert date and time according to passed timezone. Learn more →	string	Europe/London
language	no	ISO 639-1 language code (default: `en`). Learn more →	string	en
regions	no	ISO 3166-2 subdivision code. Learn more →	string	GB-ENG

Languages

caution

This functionality is only available in Starter, Business and Enterprise plans.

In order to support your global operations and as a response to our growing worldwide customer base, we've introduced language support in late 2018. By passing language's ISO 639-1 code as language (or lang) parameter, you're altering the returned holiday name in holiday.name response property to your language-of-choice. List of all ISO 639-1 language codes is available here.

All languages available for specific country are listed under availableFilters.language property.

If we don't support the language you specified, we use standard English name as a fallback.

Timezones

caution

This functionality is only available in Starter, Business and Enterprise plans.

We care about you and your business and support your global operations. For this purpose, to ease you handling different holidays in different countries and timezones, we convert all dates of all holidays in response, according to the timezone parameter, of course if you'll pass it.

We support all timezones in TZ database format.

Subdivisions

caution

This functionality is only available in Business and Enterprise plans.

Usually, the countries have several levels of administrative divisions. The common names for the principal (largest) administrative divisions are: states (i.e. "federated states", rather than sovereign states), provinces, lands, oblasts, governorates, cantons, prefectures, counties, regions, departments, and emirates.

For example, while all Australian states and territories share the major public holidays, there are some differences between states and territories in what public holidays are observed and when. There are some public holidays, like Easter Sunday, that are observed in many but not all states and only one of the territories. Then there are also public holidays, like Western Australia Day, that are only celebrated by one state (guess which one). Finally, there are public holidays like Recreation Day in Tasmania that are only observed at a regional level.

At Festivo, we're collecting both national and regional level holidays and observances. You can filter them out using regions parameter that takes comma-separated list of ISO 3166-2 subdivision codes.

Substitute holidays

Depending on country, if a holiday falls on Sunday or Saturday, the holiday is legally moved to another day, usually first following working day, e.g. next Monday. This is something we call substitute holiday. Such thing happens quite often, and to save you the burden to remember about all those complicated regulations and rules that differ between country to country, we are automatically marking such holidays with substitute flag, as well as we're returning the actual date when the holiday takes place as holiday.observed property.

Please bear in mind that sometimes those rules are overly complicated and may even differ between cities or provinces of a country. In such event, we try to cover those cases, or we use the "general" rule (e.g. in Canada we may use federal-level rule over regional).

Responses

Possible HTTP response codes

Response status codes are returned as both the HTTP status code and as part of the response body.

Code	Description
200	All okay
400	Validation error. Please refer to errors array available in received response.
401	Authorization error. Check your `api_token` parameter and if you have active subscription.
402	Payment Required. Upgrade your subscription plan. More information can be found in the `message` parameter of the response.
403	Authentication error. Requested resource/feature/filter is not available for you/in your plan, or you've exceeded your monthly requests allowance.
429	You've exceeded rate limit available in your plan.
500	Fatal error at our end. We should get reported automatically but contact us if it'll keep occurring.

Response properties

Code	Type	Description
status	int	Status code for the response.
query	object	Object containing passed query details
requestId	string	Unique identifier of the request. Include this as reference when reporting issues.
holidays.country	string	ISO 3166-1 alpha-2 code for the country that the holiday is for.
holidays.date	date	Date that the holiday actually occurs. Alterable by `timezone` parameter. Format: `RFC3339`
holidays.end	datetime	End date and time in specified timezone of the holiday. Alterable by `timezone` parameter. Format: `RFC3339`
holidays.id	string	Unique identifier for the holiday.
holidays.name	string	Name of the holiday or observance. Alterable by `language` parameter.
holidays.name_local	string	Name of the holiday or observance in the official (if available) language
holidays.observed	date	Date that the holiday is observed on. Example, some countries move holidays that land on a weekend to the following Monday. Often times, this value may be the same as date.
holidays.public	bool	Whether or not the holiday or observance is a public holiday.
holidays.start	datetime	Start date and time in specified timezone of the holiday. Alterable by `timezone` parameter. Format: `RFC3339`
holidays.subdivisions	array	Table containing ISO 3166-2 codes for states or provinces that the holiday is for.
holidays.substitute	bool	Substitute holiday is another working day off work that is designated to replace a public holiday.
holidays.type	string	Specific holiday type that this holiday has been recognised as.
holidays.weekday.date.name	string	Name of the day of the week of the holiday `date`.
holidays.weekday.date.numeric	string	Name of the day of the week of the holiday `date`.
holidays.weekday.observed.name	string	Name of the day of the week holiday is `observed` on.
holidays.weekday.observed.numeric	string	Numeric representation of the day of the week holiday is `observed` on.

Example responses

Standard request response

Below is an example status 200 standard response returned by our API:

{
  "holidays": [
    {
      "country": "US",
      "date": "2024-01-01",
      "end": "2024-01-01T23:59:59Z",
      "id": "20240101_cd5f5a6c6e09cb5af81af9e87c11a34d",
      "name": "New Year's Day",
      "name_local": "New Year's Day",
      "observed": "2024-01-01",
      "public": true,
      "start": "2024-01-01T00:00:00Z",
      "subdivisions": [],
      "substitute": false,
      "type": "public",
      "weekday": {
        "date": {
          "name": "Monday",
          "numeric": 1
        },
        "observed": {
          "name": "Monday",
          "numeric": 1
        }
      }
    },
    {
      "country": "US",
      "date": "2024-01-15",
      "end": "2024-01-15T23:59:59Z",
      "id": "20240115_6613e1e09e30661cfb73cfe3409144b2",
      "name": "Civil Rights Day",
      "name_local": "Civil Rights Day",
      "observed": "2024-01-15",
      "public": true,
      "start": "2024-01-15T00:00:00Z",
      "subdivisions": [
        "US-AZ",
        "US-NH"
      ],
      "substitute": false,
      "type": "public",
      "weekday": {
        "date": {
          "name": "Monday",
          "numeric": 1
        },
        "observed": {
          "name": "Monday",
          "numeric": 1
        }
      }
    },
    ...
  ]
}

Request using day parameter response

Below is an example status 200 response returned by our API to a single day request:

{
  "holidays": [
    {
      "country": "US",
      "date": "2024-01-01",
      "end": "2024-01-01T23:59:59Z",
      "id": "20240101_cd5f5a6c6e09cb5af81af9e87c11a34d",
      "name": "New Year's Day",
      "name_local": "New Year's Day",
      "observed": "2024-01-01",
      "public": true,
      "start": "2024-01-01T00:00:00Z",
      "subdivisions": [],
      "substitute": false,
      "type": "public",
      "weekday": {
        "date": {
          "name": "Monday",
          "numeric": 1
        },
        "observed": {
          "name": "Monday",
          "numeric": 1
        }
      }
    }
  ]
}

Introduction​

Rate limiting and throttling​

Usage​

Filters​

Premium filters​

Languages​

Timezones​

Subdivisions​

Substitute holidays​

Responses​

Possible HTTP response codes​

Response properties​

Example responses​

Standard request response​

Request using day parameter response​

Introduction

Rate limiting and throttling

Usage

Filters

Premium filters

Languages

Timezones

Subdivisions

Substitute holidays

Responses

Possible HTTP response codes

Response properties

Example responses

Standard request response

Request using day parameter response