Get access to

Public Holidays API

Retrieve public holidays for 200+ countries worldwide and for any specific year
loading

Your account
is being created.

Please don't close this window.
Oops! Something went wrong while submitting the form.
Serving millions of calls to 100,000+ developers and end users worldwide

Why 10,000+ developers love Abstract's APIs

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.

Abstract's Public Holidays API gives you the latest and most accurate 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 and cost-effective pricing

FREE

$0

no card
required!

  • 1,000 requests / month
  • Non-commercial use only
  • National holidays only
  • Query by day only
  • Current year only

STARTER

$19

per
month

  • 500,000 requests / month
  • Commercial use allowed
  • National holidays only
  • Query month, day, year
  • Current year +/- 5 years

PROFESSIONAL

$49

per
month

  • 2 million requests / month
  • Commercial use allowed
  • All holidays included
  • Query month, day, year
  • Current year +/- 20 years
  • Chat support

ENTERPRISE

$499

per
month

  • UNLIMITED requests
  • Commercial use allowed
  • All holidays included
  • Query month, day, year
  • Current year +/- 50 years
  • Premium chat support

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 plans requires a year, month, and date to be specified. 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": "",
    "state": "",
    "is_observed": true,
    "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": "",
    "state": "",
    "is_observed": true,
    "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": "",
    "state": "",
    "is_observed": true,
    "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

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

String

An optional parameter to narrow the response to a particular month. If included then the year must also be specified.

day

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.

state

String

The state in which the holiday occurs, if the holiday is that specific.

is_observed

Boolean

Whether the holiday is an observed, public holiday.

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": "",
    "state": "",
    "is_observed": true,
    "type": "public_holiday",
    "date": "1/25/2020",
    "date_year": "2020",
    "date_month":"1",
    "date_day": "25",
    "week_day": "Saturday"
}

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.

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.

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
Serving millions of calls to 100,000+ developers and end users worldwide

Frequently Asked Questions
About Subscription & Pricing

What does the API cost?

Each of our API's has a free plan as well as several paid options, which offer a greater number of requests, a higher level of data quality, and greater speed for higher prices. Please see the page above or sign into your account to view pricing for each API.

Do you have a free trial or free options for your API's?

Absolutely! We want you to try before you buy. Each of our API's has a free tier with a generous usage allowance for you to try the product out and verify that the speed and data quality work for you.

What payment options do you offer?

We use Stripe to accept payment via major debit and credit cards (Visa, Mastercard, American Express). If you cannot use those payment methods, then contact us at team at abstractapi.com to arrange for an alternative payment method.

Can I upgrade or downgrade my subscription?

Yes, you can upgrade or downgrade your subscription at any time by visiting your dashboard. If you upgrade in the middle of a billing cycle, you will be charged a pro-rated amount for your new plan through the end of the billing cycle.

Can I cancel at any time?

Yes, all of our subscriptions are month to month. You can cancel at any time, and you will not be charged again at the end of your billing cycle.

How can I cancel my subscription?

You can cancel your subscription at any time from your dashboard. Once canceled, your subscription will be active until the end your current billing cycle, and then it will be automatically moved to the free plan.

What happens if I go over my monthly quota for requests?

If your API usage exceeds the monthly limit set by your plan, then you will be charged a fee for each call over your limit. At the end of your billing period, your usage will reset again.

What if I need more requests or something else that's not offered in your plans?

We do offer enterprise plans with custom features and pricing in limited circumstances. If our public pricing plans don't work for you, then contact us (team at abstractapi.com) and we'll work something out.

Do you offer any discounts?

While we don't normally offer discounts, we do make exceptions for certain types of users and use cases. If you are a student or are engaged in academic work, or are working on a non-profit or open source project, we're happy to offer you discounts for our API's. Just email us at team at abstractapi.com.

Do you offer discounts for annual or quarterly payments?

All of our plans are currently paid month to month. We will be launching annual plans at a discount soon. If you're interested in an annual plan in the meantime, just contact us and we'll set you up.

What happens if my payment method expires?

We will typically attempt to charge your payment method up to three times after it fails. If we're still unable to collect payment, then your subscription will be automatically canceled and you'll be moved to the free plan.

Can I use the API's for a commercial project?

Yes, a paid tier of our API may be used in conjunction with a commercial project. The free tiers of our API's may not be used in commercial projects.

Public Holidays API Changelog

Last Updated on 

July 6, 2020

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.