Public Holidays API

curl --request GET \
  --url https://holidays.abstractapi.com/v1/

<?php

$curl = curl_init();

curl_setopt_array($curl, [
  CURLOPT_URL => "https://holidays.abstractapi.com/v1/",
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_ENCODING => "",
  CURLOPT_MAXREDIRS => 10,
  CURLOPT_TIMEOUT => 30,
  CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
  CURLOPT_CUSTOMREQUEST => "GET",
]);

$response = curl_exec($curl);
$err = curl_error($curl);

curl_close($curl);

if ($err) {
  echo "cURL Error #:" . $err;
} else {
  echo $response;
}

package main

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

func main() {

	url := "https://holidays.abstractapi.com/v1/"

	req, _ := http.NewRequest("GET", url, nil)

	res, _ := http.DefaultClient.Do(req)

	defer res.Body.Close()
	body, _ := io.ReadAll(res.Body)

	fmt.Println(string(body))

}

require 'uri'
require 'net/http'

url = URI("https://holidays.abstractapi.com/v1/")

http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true

request = Net::HTTP::Get.new(url)

response = http.request(request)
puts response.read_body

[
    {
        "name": "New Year's Day",
        "name_local": "",
        "language": "",
        "description": "",
        "country": "SG",
        "location": "Singapore",
        "type": "National",
        "date": "01/01/2023",
        "date_year": "2023",
        "date_month": "01",
        "date_day": "01",
        "week_day": "Sunday"
    },
    {
        "name": "New Year's Day",
        "name_local": "",
        "language": "",
        "description": "",
        "country": "SG",
        "location": "Singapore",
        "type": "National",
        "date": "01/02/2023",
        "date_year": "2023",
        "date_month": "01",
        "date_day": "02",
        "week_day": "Monday"
    },
    {
        "name": "Chinese Lunar New Year's Day",
        "name_local": "",
        "language": "",
        "description": "",
        "country": "SG",
        "location": "Singapore",
        "type": "National",
        "date": "01/23/2023",
        "date_year": "2023",
        "date_month": "01",
        "date_day": "23",
        "week_day": "Monday"
    },

    ......
    
    {
        "name": "Christmas Eve",
        "name_local": "",
        "language": "",
        "description": "",
        "country": "SG",
        "location": "Singapore",
        "type": "Observance",
        "date": "12/24/2023",
        "date_year": "2023",
        "date_month": "12",
        "date_day": "24",
        "week_day": "Sunday"
    },
    {
        "name": "Christmas Day",
        "name_local": "",
        "language": "",
        "description": "",
        "country": "SG",
        "location": "Singapore",
        "type": "National",
        "date": "12/25/2023",
        "date_year": "2023",
        "date_month": "12",
        "date_day": "25",
        "week_day": "Monday"
    },
    {
        "name": "New Year's Eve",
        "name_local": "",
        "language": "",
        "description": "",
        "country": "SG",
        "location": "Singapore",
        "type": "Observance",
        "date": "12/31/2023",
        "date_year": "2023",
        "date_month": "12",
        "date_day": "31",
        "week_day": "Sunday"
    }
]

GET

Public Holidays API

curl --request GET \
  --url https://holidays.abstractapi.com/v1/

<?php

$curl = curl_init();

curl_setopt_array($curl, [
  CURLOPT_URL => "https://holidays.abstractapi.com/v1/",
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_ENCODING => "",
  CURLOPT_MAXREDIRS => 10,
  CURLOPT_TIMEOUT => 30,
  CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
  CURLOPT_CUSTOMREQUEST => "GET",
]);

$response = curl_exec($curl);
$err = curl_error($curl);

curl_close($curl);

if ($err) {
  echo "cURL Error #:" . $err;
} else {
  echo $response;
}

package main

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

func main() {

	url := "https://holidays.abstractapi.com/v1/"

	req, _ := http.NewRequest("GET", url, nil)

	res, _ := http.DefaultClient.Do(req)

	defer res.Body.Close()
	body, _ := io.ReadAll(res.Body)

	fmt.Println(string(body))

}

require 'uri'
require 'net/http'

url = URI("https://holidays.abstractapi.com/v1/")

http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true

request = Net::HTTP::Get.new(url)

response = http.request(request)
puts response.read_body

[
    {
        "name": "New Year's Day",
        "name_local": "",
        "language": "",
        "description": "",
        "country": "SG",
        "location": "Singapore",
        "type": "National",
        "date": "01/01/2023",
        "date_year": "2023",
        "date_month": "01",
        "date_day": "01",
        "week_day": "Sunday"
    },
    {
        "name": "New Year's Day",
        "name_local": "",
        "language": "",
        "description": "",
        "country": "SG",
        "location": "Singapore",
        "type": "National",
        "date": "01/02/2023",
        "date_year": "2023",
        "date_month": "01",
        "date_day": "02",
        "week_day": "Monday"
    },
    {
        "name": "Chinese Lunar New Year's Day",
        "name_local": "",
        "language": "",
        "description": "",
        "country": "SG",
        "location": "Singapore",
        "type": "National",
        "date": "01/23/2023",
        "date_year": "2023",
        "date_month": "01",
        "date_day": "23",
        "week_day": "Monday"
    },

    ......
    
    {
        "name": "Christmas Eve",
        "name_local": "",
        "language": "",
        "description": "",
        "country": "SG",
        "location": "Singapore",
        "type": "Observance",
        "date": "12/24/2023",
        "date_year": "2023",
        "date_month": "12",
        "date_day": "24",
        "week_day": "Sunday"
    },
    {
        "name": "Christmas Day",
        "name_local": "",
        "language": "",
        "description": "",
        "country": "SG",
        "location": "Singapore",
        "type": "National",
        "date": "12/25/2023",
        "date_year": "2023",
        "date_month": "12",
        "date_day": "25",
        "week_day": "Monday"
    },
    {
        "name": "New Year's Eve",
        "name_local": "",
        "language": "",
        "description": "",
        "country": "SG",
        "location": "Singapore",
        "type": "Observance",
        "date": "12/31/2023",
        "date_year": "2023",
        "date_month": "12",
        "date_day": "31",
        "week_day": "Sunday"
    }
]

It’s simple to use: you only need to submit your api_key and a two letter country code country. The API will return the public holidays for that country.

Getting started

REST

The Public Holidays API, like all of Abstract’s APIs, is organized around REST. It is designed to use predictable, resource-oriented URLs and to use HTTP status codes to indicate errors.

HTTPS

The Public Holidays API requires all communications to be secured with TLS 1.2 or greater.

API Versions

All of Abstract’s APIs are versioned. The Public Holidays API is currently on Version 1.

Your API Key

Your API key is your unique authentication key to be used to access Abstract’s Public Holidays API. Note that each of Abstract’s APIs has a unique API key, so you will need different keys to access the Public Holidays and Email Validation APIs, for example. To authenticate your requests, you will need to append your API key to the base URL.

Base URL

https://holidays.abstractapi.com/v1/

Validation endpoint

Abstract’s Public Holidays API simply requires your unique API key and the country you’d like to get the public holidays from.

https://holidays.abstractapi.com/v1/
? api_key = YOUR_UNIQUE_API_KEY
& country = SG

This was a successful request, so the public holidays from Singapore and details associated with it are returned as the example on the right.

[
    {
        "name": "New Year's Day",
        "name_local": "",
        "language": "",
        "description": "",
        "country": "SG",
        "location": "Singapore",
        "type": "National",
        "date": "01/01/2023",
        "date_year": "2023",
        "date_month": "01",
        "date_day": "01",
        "week_day": "Sunday"
    },
    {
        "name": "New Year's Day",
        "name_local": "",
        "language": "",
        "description": "",
        "country": "SG",
        "location": "Singapore",
        "type": "National",
        "date": "01/02/2023",
        "date_year": "2023",
        "date_month": "01",
        "date_day": "02",
        "week_day": "Monday"
    },
    {
        "name": "Chinese Lunar New Year's Day",
        "name_local": "",
        "language": "",
        "description": "",
        "country": "SG",
        "location": "Singapore",
        "type": "National",
        "date": "01/23/2023",
        "date_year": "2023",
        "date_month": "01",
        "date_day": "23",
        "week_day": "Monday"
    },

    ......
    
    {
        "name": "Christmas Eve",
        "name_local": "",
        "language": "",
        "description": "",
        "country": "SG",
        "location": "Singapore",
        "type": "Observance",
        "date": "12/24/2023",
        "date_year": "2023",
        "date_month": "12",
        "date_day": "24",
        "week_day": "Sunday"
    },
    {
        "name": "Christmas Day",
        "name_local": "",
        "language": "",
        "description": "",
        "country": "SG",
        "location": "Singapore",
        "type": "National",
        "date": "12/25/2023",
        "date_year": "2023",
        "date_month": "12",
        "date_day": "25",
        "week_day": "Monday"
    },
    {
        "name": "New Year's Eve",
        "name_local": "",
        "language": "",
        "description": "",
        "country": "SG",
        "location": "Singapore",
        "type": "Observance",
        "date": "12/31/2023",
        "date_year": "2023",
        "date_month": "12",
        "date_day": "31",
        "week_day": "Sunday"
    }
]

Checking specific days, months, or years

It’s also possible to specify the day, month, or year. Note that if you specify a day, you must also include a month and year. If you specify a month, you must also specify the year. For example, this will return all the holidays in the US in January 2021:

https://holidays.abstractapi.com/v1/  
? api_key = YOUR_UNIQUE_API_KEY  
& country = US
& year = 2021
& month = 01

And this would return any holidays in the US on January 1, 2021:

https://holidays.abstractapi.com/v1/  
? api_key = YOUR_UNIQUE_API_KEY  
& country = US
& year = 2021
& month = 01
& day = 01

Note: if the query is valid but there are no holidays in the checked period, you will get a 200 response with an empty array.

Request parameters

String

required

Your unique API key. Note that each user has unique API keys for each of Abstract’s APIs, so your Public Holiday API key will not work for your IP Geolocation API, for example.

String

required

The country’s two letter ISO 3166-1 alpha-2 code.

String

The year to get the holiday(s) from. Note that this is optional on paid plans and required on free plans, and if left blank it will default to the current year.

String

The month to get the holiday(s) from, in the format of 1-12 (e.g., 1 is January, 2 is February, etc). Note that this is optional on paid plans and required on free plans, and if left blank it will default to the current month.

String

The day to get the holiday(s) from, in the format of 1-31. Note that this is optional on paid plans and required on free plans, and if left blank it will default to the current day.

Response parameters

The API response is returned in a universal and lightweight JSON format.

String

The name of the holiday.

String

The local name of the holiday.

String

If the name_local is used, then this specifies the language in which it is in.

String

A short description or additional details on the holiday, such as whether it is part of a long weekend.

String

The country in which the holiday occurs, returned directly from the request.

String

The location or region in which the holiday occurs, if the holiday is that specific.

String

The type of holiday it is (e.g., public holiday, religious holiday, etc).

String

The date on which the holiday occurs.

String

The year in which the holiday occurs.

String

The month in which the holiday occurs.

String

The day in which the holiday occurs.

String

The day of the week on which the holiday occurs (Monday, Tuesday, Wednesday, etc.)

Code samples and libraries

Please see the top of this page for code samples for these languages and more. If we’re missing a code sample, or if you’d like to contribute a code sample or library in exchange for free credits, email us at: team@abstractapi.com

Response and error codes

Whenever you make a request that fails for some reason, an error is returned also in the JSON format. The errors include an error code and description, which you can find in detail below.

Code	Type	Details
200	OK	Everything worked as expected.
400	Bad request	Bad request.
401	Unauthorized	The request was unacceptable. Typically due to the API key missing or incorrect.
422	Quota reached	The request was aborted due to insufficient API credits. (Free plans)
429	Too many requests	The request was aborted due to the number of allowed requests per second being reached. This happens on free plans as requests are limited to 1 per second.
500	Internal server error	The request could not be completed due to an error on the server side.
503	Service unavailable	The server was unavailable.

Country Codes

Below is a list of two-letter ISO 3166 Alpha 2 country codes to use when querying for a specific country.

Country name	Country code
Afghanistan	AF
Albania	AL
Algeria	DZ
American Samoa	AS
Andorra	AD
Angola	AO
Anguilla	AI
Antigua and Barbuda	AG
Argentina	AR
Armenia	AM
Aruba	AW
Australia	AU
Austria	AT
Azerbaijan	AZ
Bahrain	BH
Bangladesh	BD
Barbados	BB
Belarus	BY
Belgium	BE
Belize	BZ
Benin	BJ
Bermuda	BM
Bhutan	BT
Bolivia	BO
Bosnia and Herzegovina	BA
Botswana	BW
Brazil	BR
British Virgin Islands	VG
Brunei	BN
Bulgaria	BG
Burkina Faso	BF
Burundi	BI
Cabo Verde	CV
Cambodia	KH
Cameroon	CM
Canada	CA
Cayman Islands	KY
Central African Republic	CF
Chad	TD
Chile	CL
China	CN
Colombia	CO
Comoros	KM
Congo	CG
Congo Democratic Republic	CD
Cook Islands	CK
Costa Rica	CR
Cote d’Ivoire	CI
Croatia	HR
Cuba	CU
Curaçao	CW
Cyprus	CY
Czechia	CZ
Denmark	DK
Djibouti	DJ
Dominica	DM
Dominican Republic	DO
East Timor	TL
Ecuador	EC
Egypt	EG
El Salvador	SV
Equatorial Guinea	GQ
Eritrea	ER
Estonia	EE
eSwatini	SZ
Ethiopia	ET
Falkland Islands	FK
Faroe Islands	FO
Fiji	FJ
Finland	FI
France	FR
French Guiana	GF
French Polynesia	PF
Gabon	GA
Gambia	GM
Georgia	GE
Germany	DE
Ghana	GH
Gibraltar	GI
Greece	GR
Greenland	GL
Grenada	GD
Guadeloupe	GP
Guam	GU
Guatemala	GT
Guernsey	GG
Guinea	GN
Guinea Bissau	GW
Guyana	GY
Haiti	HT
Honduras	HN
Hong Kong	HK
Hungary	HU
Iceland	IS
India	IN
Indonesia	ID
Iran	IR
Iraq	IQ
Ireland	IE
Isle of Man	IM
Israel	IL
Italy	IT
Jamaica	JM
Japan	JP
Jersey	JE
Jordan	JO
Kazakhstan	KZ
Kenya	KE
Kiribati	KI
Kosovo	XK
Kuwait	KW
Kyrgyzstan	KG
Laos	LA
Latvia	LV
Lebanon	LB
Lesotho	LS
Liberia	LR
Libya	LY
Liechtenstein	LI
Lithuania	LT
Luxembourg	LU
Macau	MO
Madagascar	MG
Malawi	MW
Malaysia	MY
Maldives	MV
Mali	ML
Malta	MT
Marshall Islands	MH
Martinique	MQ
Mauritania	MR
Mauritius	MU
Mayotte	YT
Mexico	MX
Micronesia	FM
Moldova	MD
Monaco	MC
Mongolia	MN
Montenegro	ME
Montserrat	MS
Morocco	MA
Mozambique	MZ
Myanmar	MM
Namibia	NA
Nauru	NR
Nepal	NP
Netherlands	NL
New Caledonia	NC
New Zealand	NZ
Nicaragua	NI
Niger	NE
Nigeria	NG
North Korea	KP
North Macedonia	MK
Northern Mariana Islands	MP
Norway	NO
Oman	OM
Pakistan	PK
Palau	PW
Panama	PA
Papua New Guinea	PG
Paraguay	PY
Peru	PE
Philippines	PH
Poland	PL
Portugal	PT
Puerto Rico	PR
Qatar	QA
Reunion	RE
Romania	RO
Russia	RE
Rwanda	RW
Saint Helena	SH
Saint Kitts and Nevis	KN
Saint Lucia	LC
Saint Martin	MF
Saint Pierre and Miquelon	PM
Saint Vincent and the Grenadines	VC
Samoa	WS
San Marino	SM
Sao Tome and Principe	ST
Saudi Arabia	SA
Senegal	SN
Serbia	RS
Seychelles	SC
Sierra Leone	SL
Singapore	SG
Sint Maarten	SX
Slovakia	SK
Slovenia	SI
Solomon Islands	SB
Somalia	SO
South Africa	ZA
South Korea	KR
South Sudan	SS
Spain	ES
Sri Lanka	LK
St. Barts	BL
Sudan	SD
Suriname	SR
Sweden	SE
Switzerland	CH
Syria	SY
Taiwan	TW
Tajikistan	TJ
Tanzania	TZ
Thailand	TH
The Bahamas	BH
Togo	TG
Tonga	TO
Trinidad and Tobago	TT
Tunisia	TN
Turkey	TR
Turkmenistan	TM
Turks and Caicos Islands	TC
Tuvalu	TV
Uganda	UG
Ukraine	UA
United Arab Emirates	AE
United Kingdom	GB
United States	US
Uruguay	UY
US Virgin Islands	VI
Uzbekistan	UZ
Vanuatu	VU
Vatican City (Holy See)	VA
Venezuela	VE
Vietnam	VN
Wallis and Futuna	WF
Yemen	YE
Zambia	ZM
Zimbabwe	ZW

Introduction

Popular APIs

APIs to verify

APIs to Look up

APIs to create

Public Holidays API

Getting started

REST

HTTPS

API Versions

Your API Key

Base URL

Validation endpoint

Checking specific days, months, or years

Request parameters

Response parameters

Code samples and libraries

Response and error codes

Country Codes

​Getting started

​REST

​HTTPS

​API Versions

​Your API Key

​Base URL

​Validation endpoint

​Checking specific days, months, or years

​Request parameters

​Response parameters

​Code samples and libraries

​Response and error codes

​Country Codes

Getting started

REST

HTTPS

API Versions

Your API Key

Base URL

Validation endpoint

Checking specific days, months, or years

Request parameters

Response parameters

Code samples and libraries

Response and error codes

Country Codes