https://holidays.abstractapi.com/v1/
? api_key = YOUR_UNIQUE_API_KEY
& country = SG
"name": "New Year's Day",
"name_local": "",
"language": "",
"description": "",
"country": "SG",
"location": "",
"type": "public_holiday",
"date": "1/1/2020",
"date_year": "2020",
"date_month":"1",
"date_day": "1",
"week_day": "Wednesday"
},
}
"name": "Chinese New Year's Day",
"name_local": "",
"language": "",
"description": "Part of the long weekend",
"country": "SG",
"location": "",
"type": "public_holiday",
"date": "1/25/2020",
"date_year": "2020",
"date_month":"1",
"date_day": "25",
"week_day": "Saturday"
},
}
"name": "Second day of the Chinese New Year",
"name_local": "",
"language": "",
"description": "Part of the long weekend",
"country": "SG",
"location": "",
"type": "public_holiday",
"date": "1/26/2020",
"date_year": "2020",
"date_month":"1",
"date_day": "25",
"week_day": "Sunday"
},
...
...
Abstract's Public Holiday API is a fast, lightweight, modern, and RESTful JSON API for getting the public and religious holidays of a particular country.
It's very simple to use: you only need to submit your API key and a country, and the API will return the public holidays for that country. Additional parameters -- such as the year, month, and even day -- can be specified to determine what holidays if any exist in that timeframe.
The Public Holiday API, like all of Abstract's APIs, is organized around REST. It is designed to use predictable, resource-oriented URL's and to use HTTP status codes to indicate errors.
The Public Holiday API requires all communications to be secured TLS 1.2 or greater.
All of Abstract's API are versioned. The Public Holiday API is currently on Version 1.
Your API key is your unique authentication key to be used to access Abstract's Public Holiday API. Note that each of Abstract's API has a unique API key, so you will need different keys to access the Public Holiday and Email Validation APIs, for example. To authenticate your requests, you will need to append your API key to the base URL.
https://holidays.abstractapi.com/v1/
Abstract's Holiday API just requires your unique API key and the country that you'd like to check. Note that the free plan only allows you to query the current year. The example request below is made using an API key from a paid plan.
https://holidays.abstractapi.com/v1/
? api_key = YOUR_UNIQUE_API_KEY
& country = SG
This was a successful request, so the full list of holidays from Singapore (SG) are returned for the current year (2020).
"name": "New Year's Day",
"name_local": "",
"language": "",
"description": "",
"country": "SG",
"location": "",
"type": "public_holiday",
"date": "1/1/2020",
"date_year": "2020",
"date_month":"1",
"date_day": "1",
"week_day": "Wednesday"
},
}
"name": "Chinese New Year's Day",
"name_local": "",
"language": "",
"description": "Part of the long weekend",
"country": "SG",
"location": "",
"type": "public_holiday",
"date": "1/25/2020",
"date_year": "2020",
"date_month":"1",
"date_day": "25",
"week_day": "Saturday"
},
}
"name": "Second day of the Chinese New Year",
"name_local": "",
"language": "",
"description": "Part of the long weekend",
"country": "SG",
"location": "",
"type": "public_holiday",
"date": "1/26/2020",
"date_year": "2020",
"date_month":"1",
"date_day": "25",
"week_day": "Sunday"
},
...
...
PARAMETER
TYPE
DETAILS
api_key required
String
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 as your IP Geolocation API key, for example.
country required
String
The country's two letter ISO 3166-1 alpha-2 code.
year (required on free plans)
String
An optional parameter to narrow the response to a particular year. If not included in the request, it defaults to the current year.
month (required on free plans)
String
An optional parameter to narrow the response to a particular month. If included then the year must also be specified.
day (required on free plans)
String
An optional parameter to narrow the response to a particular day. If included then the year and month must also be specified.
The API response is returned in a universal and lightweight JSON format.
PARAMETER
TYPE
DETAILS
name
String
The name of the holiday.
name_local
String
The local name of the holiday.
language
String
If the name_local is used, then this specifies the language in which it is in.
description
String
A short description or additional details on the holiday, such as whether it is part of a long weekend.
country
String
The country in which the holiday occurs, returned directly from the request.
location
String
The location or region in which the holiday occurs, if the holiday is that specific.
type
String
The type of holiday it is (e.g., public holiday, religious holiday, etc).
date
String
The date on which the holiday occurs.
date_year
String
The year in which the holiday occurs.
date_month
String
The month in which the holiday occurs.
date_day
String
The day on which the holiday occurs.
week_day
String
The day of the week on which the holiday occurs (Monday, Tuesday, Wednesday, etc.)
In the example below, the request specifies a particular year and month in the country of Singapore:
https://holidays.abstractapi.com/v1/
? api_key = YOUR_API_KEY
& country = SG
& year = 2020
& month = 1
& day = 25
The request was valid and successful, and so it returns the single public holiday in Singapore in August 2010:
}
"name": "Chinese New Year's Day",
"name_local": "",
"language": "",
"description": "Part of the long weekend",
"country": "SG",
"location": "",
"type": "public_holiday",
"date": "1/25/2020",
"date_year": "2020",
"date_month":"1",
"date_day": "25",
"week_day": "Saturday"
}
Below is a list of two-letter ISO 3166 Alpha 2 country codes to use when querying for a specific country:
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
The Holiday API is a simple to use API that provides access to a list of past and future public holidays for every country in the world. The dates, names, and other details of holidays do change, and the Abstract Holiday API makes it easy to stay on top of these changes without investing much time or effort.
There are many potential use cases for the Holiday API, and new ones are being invented all the time. Some of the more common uses cases are the following:
These are just examples and we always love to see what unique and creative solutions our users create with the Holiday API. If you have a creative implementation that you'd like to share with us and use as a case study in exchange for free credits, just email us at team [at] abstractapi.com.
Holiday data is acquired from a variety of public and private sources. Wherever possible we attempt to use official government data that’s cross referenced by one or more additional sources. For example, in the US, the U.S. Office of Personnel Management (OPM), which serves as the chief human resources agency and personnel policy manager for the Federal Government, maintains a list of federal holidays. The State of California maintains their own set of holidays, some of which overlap with the federal government’s, and some of which do not. Abstract’s Holiday API identifies and validates all these dates so you don’t have to.
The Holiday API starts with officially-recognized government holidays as its basis for the holiday data. As mentioned above, this data is cross checked with as many other data sources as possible to ensure it's accurate. There are several other categories of holidays, such as religious holidays which may not be observed or only semi-observed by the government. In cases where the given national or state/province does not recognize the holiday, then it does not appear in our Holiday API. However, we are working on enriching our data set with non-observed religious and other such holidays. If you're interested in contributing to or using this data, please contact us.
Abstract’s Holiday API contains data for over 195 countries, as well as 600+ states and provinces for decades in the future and the past.
The countries and territories covered by the API include: Afghanistan, Albania, Algeria, American Samoa, Andorra, Angola, Anguilla, Antarctica, Antigua and Barbuda, Argentina, Armenia, Aruba, Australia, Austria, Azerbaijan, Bahamas, Bahrain, Bangladesh, Barbados, Belarus, Belgium, Belize, Benin, Bermuda, Bhutan, Bolivia, Bosnia and Herzegovina, Botswana, Bouvet Island, Brazil, British Indian Ocean Territory, Brunei Darussalam, Bulgaria, Burkina Faso, Burundi, Cambodia, Cameroon, Canada, Cape Verde, Cayman Islands, Central African Republic, Chad, Chile, China, Colombia, Comoros, Congo, Cook Islands, Costa Rica, Cote D'Ivoire (Ivory Coast), Croatia, Cuba, Cyprus, Czech Republic, Denmark, Djibouti, Dominica, Dominican Republic, East Timor, Ecuador, Egypt, El Salvador, Equatorial Guinea, Eritrea, Estonia, Ethiopia, Falkland Islands (Malvinas), Faroe Islands, Fiji, Finland, France, France, Metropolitan, French Guiana, French Polynesia, French Southern Territories, Gabon, Gambia, Georgia, Germany, Ghana, Gibraltar, Greece, Greenland, Grenada, Guadeloupe, Guam, Guatemala, Guinea, Guinea-Bissau, Guyana, Haiti, Heard and McDonald Islands, Honduras, Hong Kong, Hungary, Iceland, India, Indonesia, Iran, Iraq, Ireland, Israel, Italy, Jamaica, Japan, Jordan, Kazakhstan, Kenya, Kiribati, Korea (North), Korea (South), Kuwait, Kyrgyzstan, Laos, Latvia, Lebanon, Lesotho, Liberia, Libya, Liechtenstein, Lithuania, Luxembourg, Macau, Macedonia, Madagascar, Malawi, Malaysia, Maldives, Mali, Malta, Marshall Islands, Martinique, Mauritania, Mauritius, Mayotte, Mexico, Micronesia, Moldova, Monaco, Mongolia, Montserrat, Morocco, Mozambique, Myanmar, Namibia, Nauru, Nepal, Netherlands, Netherlands Antilles, New Caledonia, New Zealand, Nicaragua, Niger, Nigeria, Niue, Norfolk Island, Northern Mariana Islands, Norway, Oman, Pakistan, Palau, Panama, Papua New Guinea, Paraguay, Peru, Philippines, Pitcairn, Poland, Portugal, Puerto Rico, Qatar, Reunion, Romania, Russian Federation, Rwanda, Saint Kitts and Nevis, Saint Lucia, Saint Vincent and The Grenadines, Samoa, San Marino, Sao Tome and Principe, Saudi Arabia, Senegal, Seychelles, Sierra Leone, Singapore, Slovak Republic, Slovenia, Solomon Islands, Somalia, South Africa, Spain, Sri Lanka, St. Helena, St. Pierre and Miquelon, Sudan, Suriname, Svalbard and Jan Mayen Islands, Swaziland, Sweden, Switzerland, Syria, Taiwan, Tajikistan, Tanzania, Thailand, Togo, Tokelau, Tonga, Trinidad and Tobago, Tunisia, Turkey, Turkmenistan, Turks and Caicos Islands, Tuvalu, Uganda, Ukraine, United Arab Emirates, United Kingdom (Britain / UK), United States of America (USA), US Minor Outlying Islands, Uruguay, Uzbekistan, Vanuatu, Vatican City State (Holy See), Venezuela, Viet Nam, Virgin Islands (British), Virgin Islands (US), Wallis and Futuna Islands, Western Sahara, Yemen, Yugoslavia, Zaire, Zambia, and Zimbabwe.
May 30, 2023
-
Expanded holiday data to 200+ countries, including religious and non-public holidays, with weekly updates for improved accuracy.
November 17, 2020
-
Updated religious holidays for several APAC and MENA countries
July 6, 2020
-
Improved special character handling in holiday names
We've improved the handling of special characters in the names of holidays in the API response.
July 3, 2020
-
Non-public religious holidays added for India, Spain, and Italy
We updated the holiday dataset with additional religious, non-public holidays from the countries of India, Spain, and Italy.