Holidays API

Retrieve religious, non-public and public holidays for 200+ countries worldwide and for any specific year
Get started

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"
},
...
...

190+ countries
3,500 regions
Historical
and future holidays
Updated and
verified weekly
Other holidays (e.g., religious) included
accenture logonokia logologo cross icongoogle logostanford uni iconpayoneer logo

Why do 10,000+ developers trust Abstract?

Easy to implement and maintain

We built Abstract because most of the API's we've used aren't great for developers. That's why Abstract has excellent documentation, multiple easy to use libraries, and tutorials to get you started.

Speed and scale built into everything we do

Our APIs are built to power critical business processes and flows, so all our APIs are built for use at scale and at blazing speeds. These aren't just marketing phrases for, but fundamental features of our APIs.

Reliable uptime and great support

Developers trust Abstract because of our reliable uptime and excellent technical support that will help get you live quickly, keep you running smoothly, and resolve any issues you have fast.

The latest and most accurate
public and local holiday data from around the world

190+ countries and 3,500 regions covered

Abstract's database of public holidays has been global since the beginning, so it covers everywhere from Argentina to Zimbabwe, from Alabama in the US to Zhejiang in China.

Data on historical and future holidays

The holiday dataset is also very extensive in time, covering historical and future holidays ranging from 1 AD to past 2050. Simplify specify the year you need.

Holiday data updated and verified monthly

Countries alter holidays from time to time, whether it's changing the date, name, or adding new ones. So Abstract has a robust process for ensuring the data is always accurate.

Non-public, religious holidays included

For some countries our dataset also includes non public holidays, such as religious holidays, which may not be government-level holidays but which may still be observed by the population.

Simple, transparent, and cost-effective pricing

starter

$19

per
month

  • 500,000 requests
  • 1 request / second

pro

$49

per
month

  • 2,000,000 requests / month
  • 10 requests / second

scale

$99

per
month

  • 10,000,000 requests / month
  • 50 requests / second

growth

$499

per
month

  • Unlimited requests / month
  • 100 requests / second
Need more requests, enterprise-grade SLA's, faster response time, or premium data?
Contact us to learn about our Enterprise plan.

Public Holiday API Documentation

Overview

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.

REST

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.

HTTPS

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

API Versions

All of Abstract's API are versioned. The Public Holiday 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 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.

Base URL

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

Overview of the Public Holiday API

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"
},
...
...

Public Holiday API - Request Parameters

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.

Public Holiday API - Response

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.)

Example: Specifying a Year and Month to Find a Public Holiday via API

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"
}

Country Codes

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

Frequently Asked Questions
about Abstract's Holiday API

What is the Holiday API?

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.

What are some use cases for the Holiday API?

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:

  1. Improving personalization of digital or offline marketing efforts by tailoring your messaging to the holidays of each specific user once you have identified their location, such as through IP Geolocation. Conversely, you can avoid certain types of marketing on or around certain holidays.
  2. Improving expectations around service availability, such as support and operations by notifying users of local holidays.
  3. Personalizing emails, chats, and other interfaces by adapting them to or mentioning a user’s local holidays.

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.

Where does the data for the Holiday API come from?

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.

What types of holidays does the API cover?

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.

What countries, regions, and time frames does the Holiday API cover?

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.

Developers around the world love Abstract's Holiday API

Wow, I wish we had found the Holiday API sooner! We basically stopped supporting certain really powerful customization jobs because we couldn't accurately set holidays. We had been looking for something like for a while and were so happy when we got set up with Abstract's Holiday API.

Daniel Radin, Okta

We spent years hard coding a limited number of public holiday dates for key countries into our code, but it was a pain to maintain and we could only support a limited number of countries. Abstract's Holiday API lets to support every country out of the box with no additional work. Love it.

Rachel Sorenson, Prospero

The Abstract Holiday API is awesome! It's unlocked functionality and customization in my app that I had written off since it was so hard to get reliable public holiday data every country around the world. But this Abstract I feel confident in serving users from Argentina to Zimbabwe!

Richard Waterhouse, Developer

GET STARTED

Get FREE credits to start today.

Get thousands of API calls for free across all Abstract APIs.
GET YOUR FREE API KEY
The world's top engineers and organizations run on Abstract
accenture logonokia logologo cross icongoogle logostanford uni iconpayoneer logo

Public Holidays API Changelog

Last Updated on 

May 30, 2023

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.