Holiday API®
Countries Developers Use Cases Pricing Contact LoginSignup

Developer Documentation

Discover the easiest way to enhance your website or application with public holidays and observances.

Up-to-date holiday information, provided by our own API
Just one example of what you can do with Holiday API.
List Holidays

Retrieves a list public holidays and observances for countries, states and provinces. Try it in your browser.

GET /v1/holidays
Copy
$ curl -G -d country="US" -d year="2023" -d pretty
-d key="__YOUR_API_KEY__" "https://holidayapi.com/v1/holidays"
import "github.com/joshtronic/go-holidayapi"
hapi := holidayapi.NewV1("__YOUR_API_KEY__")
holidays, err := hapi.Holidays(map[string]interface{}{
  "country": "US",
  "year": "2023",
})
import { HolidayAPI } from 'holidayapi';
const key = '__YOUR_API_KEY__'
const holidayApi = new HolidayAPI({ key });
holidayApi.holidays({
  country: 'US',
  year: '2023',
});
$key = '__YOUR_API_KEY__';
$holiday_api = new \HolidayAPI\Client(['key' => $key]);
$holidays = $holiday_api->holidays([
  'country' => 'US',
  'year' => '2023',
]);
$Body = @{}
$Body.key = "__YOUR_API_KEY__"
$Body.country = "US"
$Body.year = "2023"
$Url = "https://holidayapi.com/v1/holidays"
$Result = Invoke-RestMethod -Uri $Url -Body $Body
$Result.holidays
import holidayapi
key = '__YOUR_API_KEY__'
hapi = holidayapi.v1(key)
holidays = hapi.holidays({
  'country': 'US',
  'year': '2023',
})
require 'ruby-holidayapi'
key = '__YOUR_API_KEY__'
hapi = HolidayAPI::V1.new(key)
holidays = hapi.holidays({
  'country': 'US',
  'year': '2023',
})
Required Request Parameters
country string

For countries, ISO 3166-1 alpha-2 or ISO 3166-1 alpha-3 format. For states / provinces (with our States & Provinces plan), ISO 3166-2 format. Accepts up to 10 comma separated values.

Full list of supported countries and states / provinces.

key string

Your API key.

year postive integer

4 digit year in ISO 8601 format.

Optional Request Parameters
month integer

1 or 2 digit month (1-12).

day integer

1 or 2 digit day (1-31 depending on the month). Must be used with month.

public boolean

Return only public holidays.

subdivisions boolean

Return state / province holidays alongside countrywide holidays. Available on our States & Provinces plan.

search string

Search holidays by name. Minimum 5 characters.

language string

ISO 639-1 format (with exceptions).

Full list of supported languages.

previous boolean

Return the first day of holidays that occur before the specific date. month and day are required. Cannot be used with upcoming.

upcoming boolean

Return the first day of holidays that occur after the specific date. month and day are required. Cannot be used with previous.

format string

Response format (csv, json, php, tsv, yaml and xml). Defaults to JSON.

pretty boolean

Prettifies results to be more human-readable.

Return Properties
status number

Status code for the response.

requests dictionary

Rate limit information for the current month.

requests.available integer

The remaining number of API calls you can make for the current month.

requests.used integer

Total number of API requests you have made during the current month.

requests.resets datetime string

The date and time that the current rate limits will be reset.

holidays array of dictionaries

List of holidays based on your request parameters.

holidays.name string

Name of the holiday or observance.

holidays.date date

Date that the holiday actually occurs.

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 boolean

Whether or not the holiday or observance is a public holiday.

holidays.country string

ISO code for the country, state or province that the holiday is for. For countries, ISO 3166-1 alpha-2. For states / provinces, ISO 3166-2 format.

holidays.uuid string

Unique identifier for the holiday.

holidays.weekday dictionary

Day of the week that the holiday occurs and is observed.

holidays.weekday.date.name string

Name of the day of the week that the holiday occurs. Corresponds with the date property.

holidays.weekday.date.numeric string

ISO-8601 numeric representation of the day of the week that the holiday occurs. Corresponds with the date property.

holidays.weekday.observed.name string

Name of the day of the week that the holiday is observed. Corresponds with the observed property.

holidays.weekday.observed.numeric string

ISO-8601 numeric representation of the day of the week that the holiday lands on. Corresponds with the date property.

Optional Return Properties
error string

Textual explanation of the error that ocurred.

warning string

Additional information about the data that was returned.

holidays.subdivisions array of strings

List of applicable subdivisions when using the subdivisions request parameter. Empty array denotes all subdivisions are applicable.

Sample Holidays Response
{
    "status": 200,

  + "requests": { ... },
  - "requests": {
        "used": 493,
        "available": 507,
        "resets": "2024-12-01 00:00:00"
    },
  + "holidays": [ ... ]
  - "holidays": [
        {
            "name": "New Year's Day",
            "date": "2015-01-01",
            "observed": "2015-01-01",
            "public": true,
            "country": "US",
            "uuid": "82f78b8a-019e-479e-a19f-99040275f9bf",
            "weekday": {
                "date": {
                    "name": "Thursday",
                    "numeric": 4
                },
                "observed": {
                    "name": "Thursday",
                    "numeric": 4
                }
            }
        },
        {
            "name": "Mother's Day",
            "date": "2015-05-10",
            "observed": "2015-05-10",
            "public": false,
            "country": "US",
            "uuid": "0746cfc7-6432-4dcc-bc75-dfef56c41086",
            "weekday": {
                "date": {
                    "name": "Sunday",
                    "numeric": 7
                },
                "observed": {
                    "name": "Sunday",
                    "numeric": 7
                }
            }
        },
        {
            "name": "Independence Day",
            "date": "2015-07-04",
            "observed": "2015-07-03",
            "public": true,
            "country": "US",
            "uuid": "88268759-9b90-468c-804f-b729b8418e7c",
            "weekday": {
                "date": {
                    "name": "Saturday",
                    "numeric": 6
                },
                "observed": {
                    "name": "Friday",
                    "numeric": 5
                }
            }
        }
    ]
}
List Countries

Retrieves a list countries with states and provinces. Full list of supported countries and states / provinces. Try it in your browser.

GET /v1/countries
Copy
$ curl -G -d pretty
-d key="__YOUR_API_KEY__" "https://holidayapi.com/v1/countries"
import { HolidayAPI } from 'holidayapi';
const key = '__YOUR_API_KEY__'
const holidayApi = new HolidayAPI({ key });
holidayApi.countries();
$key = '__YOUR_API_KEY__';
$holiday_api = new \HolidayAPI\Client(['key' => $key]);
$holidays = $holiday_api->countries();
$Body = @{}
$Body.key = "__YOUR_API_KEY__"
$Url = "https://holidayapi.com/v1/countries"
$Result = Invoke-RestMethod -Uri $Url -Body $Body
$Result.countries
Required Request Parameters
key string

Your API key.

Optional Request Parameters
country string

Return only the country with the specified code.

search string

Search countries by code and name. Minimum 2 characters.

public boolean

Return only countries that have public holidays.

format string

Response format (csv, json, php, tsv, yaml and xml). Defaults to JSON.

pretty boolean

Prettifies results to be more human-readable.

Return Properties
status number

Status code for the response.

requests dictionary

Rate limit information for the current month.

requests.available integer

The remaining number of API calls you can make for the current month.

requests.used integer

Total number of API requests you have made during the current month.

requests.resets datetime string

The date and time that the current rate limits will be reset.

countries array of dictionaries

List of countries based on your request parameters.

countries.code string

ISO 3166-1 alpha-2 code for the country.

countries.name string

Name of the country.

countries.codes dictionary of country codes

Not every system uses ISO 3166-1 alpha-2 codes. These codes provide an easy way to map ISO 3166-1 alpha 2 codes back to the codes your system uses.

countries.codes.alpha-2 string

ISO 3166-1 alpha-2 code for the country.

countries.codes.alpha-3 string

ISO 3166-1 alpha-3 code for the country.

countries.codes.numeric integer

ISO 3166-1 numeric code for the country.

countries.languages array of strings

Spoken languages for the country. Use with /v1/holidays to request holidays in a language other than English.

countries.currencies array of dictionaries

Currencies accepted as legal tender in the country.

countries.currencies.alpha string

ISO 4217 alpha code for the currency.

countries.flag URL string

URL to a 64x64 image of the country's flag, courtesy of Country Flags API.

countries.subdivisions array of dictionaries

Many countries are broken down into of smaller subdivisions. These subdivisions go by different names, like states or provinces and in some scenarios may represent countries or nations. For simplicity, we refer to these subdivisions collectively as States & Provinces.

countries.subdivisions.code string

ISO 3166-2 code for the state / province. Use with /v1/holidays to request holidays for a specific state / province.

countries.subdivisions.name string

Name of the state / province.

countries.subdivisions.languages array of strings

Spoken languages for the state / province. Use with /v1/holidays to request holidays in a language other than English.

countries.weekend array of dictionaries

Days of the week that are considered weekends (non-working days) in the country.

countries.weekend.name string

Name of the day of the week that the weekend day occurs.

countries.weekend.numeric string

ISO-8601 numeric representation of the day of the week that the weekend day occurs.

Optional Return Properties
error string

Textual explanation of the error that ocurred.

warning string

Additional information about the data that was returned.

Sample Countries Response
{
    "status": 200,

  + "requests": { ... },
  - "requests": {
        "used": 493,
        "available": 507,
        "resets": "2024-12-01 00:00:00"
    },
  + "countries": [ ... ]
  - "countries": [
        {
            "code": "ST",
            "name": "Sao Tome and Principe",
            "codes": {
                "alpha-2": "ST",
                "alpha-3": "STP",
                "numeric": 678
            },
            "languages": [
                "pt"
            ],
            "currencies": [
                {
                    "alpha": "STN"
                }
            ]
            "flag": "https:\/\/flagsapi.com\/ST\/flat\/64.png",
            "subdivisions": [
                {
                    "code": "ST-P",
                    "name": "Principe",
                    "languages": [
                        "pt"
                    ]
                },
                {
                    "code": "ST-S",
                    "name": "São Tomé",
                    "languages": [
                        "pt"
                    ]
                }
            ]
        }
    ]
}
List Languages

Retrieves a list languages. Full list of supported languages. Try it in your browser.

GET /v1/languages
Copy
$ curl -G -d pretty
-d key="__YOUR_API_KEY__" "https://holidayapi.com/v1/languages"
import { HolidayAPI } from 'holidayapi';
const key = '__YOUR_API_KEY__'
const holidayApi = new HolidayAPI({ key });
holidayApi.languages();
$key = '__YOUR_API_KEY__';
$holiday_api = new \HolidayAPI\Client(['key' => $key]);
$holidays = $holiday_api->languages();
$Body = @{}
$Body.key = "__YOUR_API_KEY__"
$Url = "https://holidayapi.com/v1/languages"
$Result = Invoke-RestMethod -Uri $Url -Body $Body
$Result.languages
Required Request Parameters
key string

Your API key.

Optional Request Parameters
language string

Return only the language with the specified code.

search string

Search languages by code and name. Minimum 2 characters.

format string

Response format (csv, json, php, tsv, yaml and xml). Defaults to JSON.

pretty boolean

Prettifies results to be more human-readable.

Return Properties
status number

Status code for the response.

requests dictionary

Rate limit information for the current month.

requests.available integer

The remaining number of API calls you can make for the current month.

requests.used integer

Total number of API requests you have made during the current month.

requests.resets datetime string

The date and time that the current rate limits will be reset.

languages array of dictionaries

List of languages based on your request parameters.

languages.code string

ISO-639-1, ISO-639-2 (for Cebuano, Hawaiian and Hmong), or BCP-47 (for Chinese) code for the language.

languages.name string

Name of the language.

Optional Return Properties
error string

Textual explanation of the error that ocurred.

warning string

Additional information about the data that was returned.

Sample Languages Response
{
    "status": 200,

  + "requests": { ... },
  - "requests": {
        "used": 493,
        "available": 507,
        "resets": "2024-12-01 00:00:00"
    },
  + "languages": [ ... ]
  - "languages": [
        {
            "code": "ar",
            "name": "Arabic"
        },
        {
            "code": "en",
            "name": "English"
        },
        {
            "code": "es",
            "name": "Spanish, Castilian"
        },
        {
            "code": "hi",
            "name": "Hindi"
        },
        {
            "code": "zh",
            "name": "Chinese (Simplified)"
        }
    ]
}
Get Workday

Calculates the workday (based on country's workweek) that occurs a given number of days after a date. Try it in your browser.

GET /v1/workday
Copy
$ curl -G -d country="US" -d start="2023-11-21" -d days="7" -d pretty
-d key="__YOUR_API_KEY__" "https://holidayapi.com/v1/workday"
import { HolidayAPI } from 'holidayapi';
const key = '__YOUR_API_KEY__'
const holidayApi = new HolidayAPI({ key });
holidayApi.workday({
  country: 'US',
  start: '2023-11-21',
  days: '7',
});
$key = '__YOUR_API_KEY__';
$holiday_api = new \HolidayAPI\Client(['key' => $key]);
$holidays = $holiday_api->workday([
  'country' => 'US',
  'start' => '2023-11-21',
  'days' => '7',
]);
$Body = @{}
$Body.key = "__YOUR_API_KEY__"
$Body.country = "US"
$Body.start = "2023-11-21"
$Body.days = "7"
$Url = "https://holidayapi.com/v1/holidays"
$Result = Invoke-RestMethod -Uri $Url -Body $Body
$Result.workday
Required Request Parameters
key string

Your API key.

country string

For countries, ISO 3166-1 alpha-2 or ISO 3166-1 alpha-3 format. For states / provinces (with our States & Provinces plan), ISO 3166-2 format.

Full list of supported countries and states / provinces.

start date

The date (in YYYY-MM-DD format) from which to begin counting.

days non-zero integer

Number of working / business days to advance (positive integer) or retrogress (negative integer) from start.

Optional Request Parameters
format string

Response format (csv, json, php, tsv, yaml and xml). Defaults to JSON.

pretty boolean

Prettifies results to be more human-readable.

Return Properties
status number

Status code for the response.

requests dictionary

Rate limit information for the current month.

requests.available integer

The remaining number of API calls you can make for the current month.

requests.used integer

Total number of API requests you have made during the current month.

requests.resets datetime string

The date and time that the current rate limits will be reset.

date date

The date of the calculated workday.

weekday dictionary

Day of the week that the workday occurs.

weekday.name string

Name of the day of the week that the workday occurs. Corresponds with the date property.

weekday.numeric string

ISO-8601 numeric representation of the day of the week that the workday occurs. Corresponds with the date property.

Optional Return Properties
error string

Textual explanation of the error that ocurred.

warning string

Additional information about the data that was returned.

Sample Workday Response
{
    "status": 200,

  + "requests": { ... },
  - "requests": {
        "used": 493,
        "available": 507,
        "resets": "2024-12-01 00:00:00"
    },
  + "workday": { ... }
  - "workday": {
        "date": "2019-07-16",
        "date": "weekday": {
            "name": "Tuesday",
            "numeric": "1"
        }
    }
}
Get Workdays

Calculates the number of workdays (based on country's workweek) that occur between a given date range. Try it in your browser.

GET /v1/workdays
Copy
$ curl -G -d country="US" -d start="2023-11-21" -d end="2023-12-01" -d pretty
-d key="__YOUR_API_KEY__" "https://holidayapi.com/v1/workdays"
import { HolidayAPI } from 'holidayapi';
const key = '__YOUR_API_KEY__'
const holidayApi = new HolidayAPI({ key });
holidayApi.workdays({
  country: 'US',
  start: '2023-11-21',
  end: '2023-12-01',
});
$key = '__YOUR_API_KEY__';
$holiday_api = new \HolidayAPI\Client(['key' => $key]);
$holidays = $holiday_api->workdays([
  'country' => 'US',
  'start' => '2023-11-21',
  'end' => '2023-12-01',
]);
$Body = @{}
$Body.key = "__YOUR_API_KEY__"
$Body.country = "US"
$Body.start = "2023-11-21"
$Body.end = "2023-12-01"
$Url = "https://holidayapi.com/v1/holidays"
$Result = Invoke-RestMethod -Uri $Url -Body $Body
$Result.workdays
Required Request Parameters
key string

Your API key.

country string

For countries, ISO 3166-1 alpha-2 or ISO 3166-1 alpha-3 format. For states / provinces (with our States & Provinces plan), ISO 3166-2 format.

Full list of supported countries and states / provinces.

start date

The date (in YYYY-MM-DD format) from which to begin counting.

end date

The date (in YYYY-MM-DD format) to count until.

Optional Request Parameters
format string

Response format (csv, json, php, tsv, yaml and xml). Defaults to JSON.

pretty boolean

Prettifies results to be more human-readable.

Return Properties
status number

Status code for the response.

requests dictionary

Rate limit information for the current month.

requests.available integer

The remaining number of API calls you can make for the current month.

requests.used integer

Total number of API requests you have made during the current month.

requests.resets datetime string

The date and time that the current rate limits will be reset.

workdays integer

Number of working / business days between the specified start and end dates.

Optional Return Properties
error string

Textual explanation of the error that ocurred.

warning string

Additional information about the data that was returned.

Sample Workdays Response
{
    "status": 200,

  + "requests": { ... },
  - "requests": {
        "used": 493,
        "available": 507,
        "resets": "2024-12-01 00:00:00"
    },
    "workdays": 13
}
Response Status Codes

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

200
Success! Everything is A-OK.
400
Something is wrong with your request parameters.
401
Unauthorized request. Did you remember your API key?
402
Upgrade required or account is delinquent. Payment is required.
403
Insecure request. HTTPS requests only.
429
Monthly rate limit exceeded.
500
Something went wrong on our end and we've been notified.
Rate Limits

Monthly rate limits vary by plan. Once exceeded, the API will return the 429 status code. You can easily track your usage for the current month via the requests property in the response body.

Holiday API Client Libraries

Kick-start your next project with our official and community contributed libraries
or generate your own from our OpenAPI definition.

OFFICIAL
Go
OFFICIAL
Node.js
OFFICIAL
PHP
OFFICIAL
Python
OFFICIAL
Ruby
COMMUNITY
C#
COMMUNITY
CodeIgniter
COMMUNITY
Feign
COMMUNITY
Go
COMMUNITY
Java
COMMUNITY
R
COMMUNITY
Raku
COMMUNITY
Rust

Guides

Determining if a weekend is a long weekend
Understanding countries and subdivisions