Public Holidays API

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.

​

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

​

Response parameters

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

​

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.

​

Country Codes

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