Introduction

Welcome to API documents for holidays.rest, a public and bank holidays API that is highly scalable, flexible and easy to use.

Authentication

To authorize, use Bearer authentication by passing your API key in the Authorization header with each request:

curl "https://api.holidays.rest/v1/$ENDPOINT" \
  -H "Authorization: Bearer YOUR_API_KEY"

import (
  "fmt"
  "io/ioutil"
  "net/http"
)

func main() {
  req, _ := http.NewRequest("GET", "https://api.holidays.rest/v1/$ENDPOINT", nil)
  req.Header.Add("Authorization", "Bearer YOUR_API_KEY")

  resp, _ := http.DefaultClient.Do(req)
  defer resp.Body.Close()

  fmt.Println(string(ioutil.ReadAll(resp.Body)))
}

require 'net/http'

response = Net::HTTP.get_response(
  URI('https://api.holidays.rest/v1/$ENDPOINT'),
  { 'Authorization' => 'Bearer YOUR_API_KEY' }
)

fetch('https://api.holidays.rest/v1/$ENDPOINT', {
  headers: {
    'Authorization': 'Bearer YOUR_API_KEY'
  }
})
.then(response => response.json())
.then(data => console.log(data));

import requests

response = requests.get(
    'https://api.holidays.rest/v1/$ENDPOINT',
    headers={'Authorization': 'Bearer YOUR_API_KEY'}
)
data = response.json()

import java.net.http.HttpClient;
import java.net.http.HttpRequest;
import java.net.http.HttpResponse;
import java.net.URI;

HttpClient client = HttpClient.newHttpClient();
HttpRequest request = HttpRequest.newBuilder()
    .uri(URI.create("https://api.holidays.rest/v1/$ENDPOINT"))
    .header("Authorization", "Bearer YOUR_API_KEY")
    .build();

HttpResponse<String> response = client.send(request, 
    HttpResponse.BodyHandlers.ofString());
String data = response.body();

Make sure to replace YOUR_API_KEY with your API key.

holidays.rest uses API keys with Bearer authentication to allow access to the API. You can register a new API key at our members area.

holidays.rest expects for the API key to be included in all API requests to the server in a header that looks like the following:

Authorization: Bearer YOUR_API_KEY

You must replace YOUR_API_KEY with your personal API key.

Response Format

All responses are formatted in JSON by default. However, you can request responses in XML, YAML and CSV formats by adding the response query parameter as follows:

Format	URL	Note
json	`https://api.holidays.rest/v1/$ENDPOINT?response=json`	default when no format is specified
xml	`https://api.holidays.rest/v1/$ENDPOINT?response=xml`
yaml	`https://api.holidays.rest/v1/$ENDPOINT?response=yaml`
csv	`https://api.holidays.rest/v1/$ENDPOINT?response=csv`

Holidays

curl "https://api.holidays.rest/v1/holidays?country=$COUNTRY_CODE&year=$YEAR" \
  -H "Authorization: Bearer YOUR_API_KEY"

import (
  "fmt"
  "io/ioutil"
  "net/http"
)

func main() {
  req, _ := http.NewRequest("GET", "https://api.holidays.rest/v1/holidays?country=$COUNTRY_CODE&year=$YEAR", nil)
  req.Header.Add("Authorization", "Bearer YOUR_API_KEY")

  resp, _ := http.DefaultClient.Do(req)
  defer resp.Body.Close()

  fmt.Println(string(ioutil.ReadAll(resp.Body)))
}

require 'net/http'

response = Net::HTTP.get_response(
  URI('https://api.holidays.rest/v1/holidays?country=$COUNTRY_CODE&year=$YEAR'),
  { 'Authorization' => 'Bearer YOUR_API_KEY' }
)

fetch('https://api.holidays.rest/v1/holidays?country=$COUNTRY_CODE&year=$YEAR', {
  headers: {
    'Authorization': 'Bearer YOUR_API_KEY'
  }
})
.then(response => response.json())
.then(data => console.log(data));

import requests

response = requests.get(
    'https://api.holidays.rest/v1/holidays?country=$COUNTRY_CODE&year=$YEAR',
    headers={'Authorization': 'Bearer YOUR_API_KEY'}
)
data = response.json()

import java.net.http.HttpClient;
import java.net.http.HttpRequest;
import java.net.http.HttpResponse;
import java.net.URI;

HttpClient client = HttpClient.newHttpClient();
HttpRequest request = HttpRequest.newBuilder()
    .uri(URI.create("https://api.holidays.rest/v1/holidays?country=$COUNTRY_CODE&year=$YEAR"))
    .header("Authorization", "Bearer YOUR_API_KEY")
    .build();

HttpResponse<String> response = client.send(request, 
    HttpResponse.BodyHandlers.ofString());
String data = response.body();

The above command returns JSON structured like this:

[
  ...
  {
    "country_code":"AT",
    "country_name":"Austria",
    "date":"2024-11-15",
    "name":{
      "en":"Saint Leopold's Day",
    },
    "isNational":false,
    "isReligious":true,
    "isLocal":true,
    "isEstimate":false,
    "day":{
      "actual":"Friday",
      "observed":"Friday"
    },
    "religion":"Christianity",
    "regions":[
      "3",
      "9"
    ]
  }
  ...
]

This endpoint retrieves all bank and public holidays for a specific country and year.

HTTP Request

GET https://api.holidays.rest/v1/holidays

Query Parameters

Parameter	Mandatory	Multiple Values	Description
`country`	true	No	Country code in ISO-3166 alpha-2 format
`year`	true	No	Year in YYYY format
`month`	false	No	Month in M or MM format
`day`	false	No	Day in D or DD format
`type`	false	Yes	Can be one of; `religious`, `national`, `local`, or a combination of multiple ones in a comma-separated way.
`religion`	false	Yes	Can be one of the religion codes, or a combination of multiple ones in a comma-separated way. Possible values can be obtained from the religion codes.
`region`	false	Yes	Can be one of the region codes, or a combination of multiple ones in a comma-separated way. Possible values can be obtained from the country endpoint.
`lang`	false	Yes	Language code(s) to return holiday names in various languages. Possible values can be obtained from the languages endpoint.

Religion codes

Code	Religion
1	Christianity
2	Islam
3	Buddhism
4	Confucianism
5	Hinduism
6	Jainism
7	Judaism
8	Sikhism
9	Yazidism
10	Zoroastrianism
11	Baha-i Faith

Examples

Filter out holidays for a specific type (e.g. national):

?country=DE&year=2024&type=national

Filter out holidays for multiple types (e.g. local or religious):

?country=DE&year=2024&type=local,religious

Filter out holidays for a specific religion:

?country=BA&year=2024&religion=2

Filter out holidays for multiple religions:

?country=BA&year=2024&religion=1,2

Filter out holidays for a specific region:

?country=BA&year=2024&region=BIH

Filter out holidays for multiple regions:

?country=BA&year=2024&region=BIH,SRP

Fetch localized holiday names in a specific language:

?country=AT&year=2024&lang=de

Fetch localized holiday names in multiple languages:

?country=AT&year=2024&lang=de,en,tr

Combining Multiple Filters

The holidays endpoint supports combining multiple filters to retrieve more complex queries. All the query string parameters that were listed above can be chained together to filter the results flexibly. For example to fetch "local" holidays for "Christianity" in "June" in "BIH" region of Bosnia and Herzegovina as "xml" and in "German" and "Japanese" languages, a query string would be as follows:

?country=BA&year=2024&month=6&type=local&region=BIH&religion=2&response=xml&lang=de,ja

<response>
    <item>
        <country_code>BA</country_code>
        <country_name>Bosnia and Herzegovina</country_name>
        <date>2024-06-16</date>
        <name de="Opferfest" ja="イード・アル・アドハー"/>
        <isNational>false</isNational>
        <isReligious>true</isReligious>
        <isLocal>true</isLocal>
        <isEstimate>false</isEstimate>
        <day actual="Sunday" observed="Sunday"/>
        <religion>Islam</religion>
        <regions>
            <item>BIH</item>
        </regions>
    </item>
</response>

Countries

curl "https://api.holidays.rest/v1/countries" \
  -H "Authorization: Bearer YOUR_API_KEY"

import (
  "fmt"
  "io/ioutil"
  "net/http"
)

func main() {
  req, _ := http.NewRequest("GET", "https://api.holidays.rest/v1/countries", nil)
  req.Header.Add("Authorization", "Bearer YOUR_API_KEY")

  resp, _ := http.DefaultClient.Do(req)
  defer resp.Body.Close()

  fmt.Println(string(ioutil.ReadAll(resp.Body)))
}

require 'net/http'

response = Net::HTTP.get_response(
  URI('https://api.holidays.rest/v1/countries'),
  { 'Authorization' => 'Bearer YOUR_API_KEY' }
)

fetch('https://api.holidays.rest/v1/countries', {
  headers: {
    'Authorization': 'Bearer YOUR_API_KEY'
  }
})
.then(response => response.json())
.then(data => console.log(data));

import requests

response = requests.get(
    'https://api.holidays.rest/v1/countries',
    headers={'Authorization': 'Bearer YOUR_API_KEY'}
)
data = response.json()

import java.net.http.HttpClient;
import java.net.http.HttpRequest;
import java.net.http.HttpResponse;
import java.net.URI;

HttpClient client = HttpClient.newHttpClient();
HttpRequest request = HttpRequest.newBuilder()
    .uri(URI.create("https://api.holidays.rest/v1/countries"))
    .header("Authorization", "Bearer YOUR_API_KEY")
    .build();

HttpResponse<String> response = client.send(request, 
    HttpResponse.BodyHandlers.ofString());
String data = response.body();

The above command returns JSON structured like this:

[
  ...
  {
    "name":"Germany",
    "long_name":"The Federal Republic of Germany",
    "region":"Europe",
    "subregion":"Western Europe",
    "world_region":"EMEA",
    "alpha2":"DE"
  },
  {
    "name":"Türkiye",
    "long_name":"The Republic of Türkiye",
    "region":"Asia",
    "subregion":"Western Asia",
    "world_region":"EMEA",
    "alpha2":"TR"
  },
  {
    "name":"Ukraine",
    "long_name":"Ukraine",
    "region":"Europe",
    "subregion":"Eastern Europe",
    "world_region":"EMEA",
    "alpha2":"UA"
  },
  ...
]

This endpoint retrieves all countries. You can use the alpha2 code to retrieve a specific country including its subdivisions or public holidays for a specific country.

HTTP Request

GET https://api.holidays.rest/v1/countries

Country

curl "https://api.holidays.rest/v1/country/$COUNTRY_CODE" \
  -H "Authorization: Bearer YOUR_API_KEY"

import (
  "fmt"
  "io/ioutil"
  "net/http"
)

func main() {
  req, _ := http.NewRequest("GET", "https://api.holidays.rest/v1/country/$COUNTRY_CODE", nil)
  req.Header.Add("Authorization", "Bearer YOUR_API_KEY")

  resp, _ := http.DefaultClient.Do(req)
  defer resp.Body.Close()

  fmt.Println(string(ioutil.ReadAll(resp.Body)))
}

require 'net/http'

response = Net::HTTP.get_response(
  URI('https://api.holidays.rest/v1/country/$COUNTRY_CODE'),
  { 'Authorization' => 'Bearer YOUR_API_KEY' }
)

fetch('https://api.holidays.rest/v1/country/$COUNTRY_CODE', {
  headers: {
    'Authorization': 'Bearer YOUR_API_KEY'
  }
})
.then(response => response.json())
.then(data => console.log(data));

import requests

response = requests.get(
    'https://api.holidays.rest/v1/country/$COUNTRY_CODE',
    headers={'Authorization': 'Bearer YOUR_API_KEY'}
)
data = response.json()

import java.net.http.HttpClient;
import java.net.http.HttpRequest;
import java.net.http.HttpResponse;
import java.net.URI;

HttpClient client = HttpClient.newHttpClient();
HttpRequest request = HttpRequest.newBuilder()
    .uri(URI.create("https://api.holidays.rest/v1/country/$COUNTRY_CODE"))
    .header("Authorization", "Bearer YOUR_API_KEY")
    .build();

HttpResponse<String> response = client.send(request, 
    HttpResponse.BodyHandlers.ofString());
String data = response.body();

The above command returns JSON structured like this:

{
  "name":"United States of America",
  "long_name":"The United States of America",
  "region":"Americas",
  "subregion":"Northern America",
  "world_region":"AMER",
  "alpha2":"US",
  "subdivisions":[
    {
      "name":"Alaska",
      "alpha2":"AK"
    },
    {
      "name":"Alabama",
      "alpha2":"AL"
    },
    {
      "name":"Arkansas",
      "alpha2":"AR"
    },
    ...
  ]
}

This endpoint retrieves a specific country, including its subdivisions. You can use the alpha2 code to retrieve public holidays of a region when calling the holidays endpoint.

HTTP Request

GET https://api.holidays.rest/v1/country/$COUNTRY_CODE

Path Parameters

Parameter	Description
`COUNTRY_CODE`	Country code in ISO-3166 alpha-2 format

Languages

curl "https://api.holidays.rest/v1/languages" \
  -H "Authorization: Bearer YOUR_API_KEY"

import (
  "fmt"
  "io/ioutil"
  "net/http"
)

func main() {
  req, _ := http.NewRequest("GET", "https://api.holidays.rest/v1/languages", nil)
  req.Header.Add("Authorization", "Bearer YOUR_API_KEY")

  resp, _ := http.DefaultClient.Do(req)
  defer resp.Body.Close()

  fmt.Println(string(ioutil.ReadAll(resp.Body)))
}

require 'net/http'

response = Net::HTTP.get_response(
  URI('https://api.holidays.rest/v1/languages'),
  { 'Authorization' => 'Bearer YOUR_API_KEY' }
)

fetch('https://api.holidays.rest/v1/languages', {
  headers: {
    'Authorization': 'Bearer YOUR_API_KEY'
  }
})
.then(response => response.json())
.then(data => console.log(data));

import requests

response = requests.get(
    'https://api.holidays.rest/v1/languages',
    headers={'Authorization': 'Bearer YOUR_API_KEY'}
)
data = response.json()

import java.net.http.HttpClient;
import java.net.http.HttpRequest;
import java.net.http.HttpResponse;
import java.net.URI;

HttpClient client = HttpClient.newHttpClient();
HttpRequest request = HttpRequest.newBuilder()
    .uri(URI.create("https://api.holidays.rest/v1/languages"))
    .header("Authorization", "Bearer YOUR_API_KEY")
    .build();

HttpResponse<String> response = client.send(request, 
    HttpResponse.BodyHandlers.ofString());
String data = response.body();

The above command returns JSON structured like this:

[
  ...
  {
    "alpha2":"en",
    "name":"English",
    "supported":true
  },
  {
    "alpha2":"de",
    "name":"German",
    "supported":true
  },
  {
    "alpha2":"tr",
    "name":"Turkish",
    "supported":true
  }
  ...
]

This endpoint retrieves all languages that are supported by holidays.rest when retrieving public holidays. By default, the API returns holiday names in all languages that are listed by this endpoint. However, if you want to filter specific languages, you can use the lang query parameter and alpha2 code of the language.

HTTP Request

GET https://api.holidays.rest/v1/languages

Errors

The holidays.rest API uses the following error codes:

Error Code	Meaning
400	Bad Request -- Your request is invalid.
401	Unauthorized -- Your API key is wrong.
404	Not Found -- The specified resource could not be found.
500	Internal Server Error -- We had a problem with our server. Try again later.
503	Service Unavailable -- We're temporarily offline for maintenance. Please try again later.