GET
/
v1
/

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

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

country
String
required

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

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

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

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

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 in which the holiday occurs.

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

CodeTypeDetails
200OKEverything worked as expected.
400Bad requestBad request.
401UnauthorizedThe request was unacceptable. Typically due to the API key missing or incorrect.
422Quota reachedThe request was aborted due to insufficient API credits. (Free plans)
429Too many requestsThe 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.
500Internal server errorThe request could not be completed due to an error on the server side.
503Service unavailableThe 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 nameCountry code
AfghanistanAF
AlbaniaAL
AlgeriaDZ
American SamoaAS
AndorraAD
AngolaAO
AnguillaAI
Antigua and BarbudaAG
ArgentinaAR
ArmeniaAM
ArubaAW
AustraliaAU
AustriaAT
AzerbaijanAZ
BahrainBH
BangladeshBD
BarbadosBB
BelarusBY
BelgiumBE
BelizeBZ
BeninBJ
BermudaBM
BhutanBT
BoliviaBO
Bosnia and HerzegovinaBA
BotswanaBW
BrazilBR
British Virgin IslandsVG
BruneiBN
BulgariaBG
Burkina FasoBF
BurundiBI
Cabo VerdeCV
CambodiaKH
CameroonCM
CanadaCA
Cayman IslandsKY
Central African RepublicCF
ChadTD
ChileCL
ChinaCN
ColombiaCO
ComorosKM
CongoCG
Congo Democratic RepublicCD
Cook IslandsCK
Costa RicaCR
Cote d’IvoireCI
CroatiaHR
CubaCU
CuraçaoCW
CyprusCY
CzechiaCZ
DenmarkDK
DjiboutiDJ
DominicaDM
Dominican RepublicDO
East TimorTL
EcuadorEC
EgyptEG
El SalvadorSV
Equatorial GuineaGQ
EritreaER
EstoniaEE
eSwatiniSZ
EthiopiaET
Falkland IslandsFK
Faroe IslandsFO
FijiFJ
FinlandFI
FranceFR
French GuianaGF
French PolynesiaPF
GabonGA
GambiaGM
GeorgiaGE
GermanyDE
GhanaGH
GibraltarGI
GreeceGR
GreenlandGL
GrenadaGD
GuadeloupeGP
GuamGU
GuatemalaGT
GuernseyGG
GuineaGN
Guinea BissauGW
GuyanaGY
HaitiHT
HondurasHN
Hong KongHK
HungaryHU
IcelandIS
IndiaIN
IndonesiaID
IranIR
IraqIQ
IrelandIE
Isle of ManIM
IsraelIL
ItalyIT
JamaicaJM
JapanJP
JerseyJE
JordanJO
KazakhstanKZ
KenyaKE
KiribatiKI
KosovoXK
KuwaitKW
KyrgyzstanKG
LaosLA
LatviaLV
LebanonLB
LesothoLS
LiberiaLR
LibyaLY
LiechtensteinLI
LithuaniaLT
LuxembourgLU
MacauMO
MadagascarMG
MalawiMW
MalaysiaMY
MaldivesMV
MaliML
MaltaMT
Marshall IslandsMH
MartiniqueMQ
MauritaniaMR
MauritiusMU
MayotteYT
MexicoMX
MicronesiaFM
MoldovaMD
MonacoMC
MongoliaMN
MontenegroME
MontserratMS
MoroccoMA
MozambiqueMZ
MyanmarMM
NamibiaNA
NauruNR
NepalNP
NetherlandsNL
New CaledoniaNC
New ZealandNZ
NicaraguaNI
NigerNE
NigeriaNG
North KoreaKP
North MacedoniaMK
Northern Mariana IslandsMP
NorwayNO
OmanOM
PakistanPK
PalauPW
PanamaPA
Papua New GuineaPG
ParaguayPY
PeruPE
PhilippinesPH
PolandPL
PortugalPT
Puerto RicoPR
QatarQA
ReunionRE
RomaniaRO
RussiaRE
RwandaRW
Saint HelenaSH
Saint Kitts and NevisKN
Saint LuciaLC
Saint MartinMF
Saint Pierre and MiquelonPM
Saint Vincent and the GrenadinesVC
SamoaWS
San MarinoSM
Sao Tome and PrincipeST
Saudi ArabiaSA
SenegalSN
SerbiaRS
SeychellesSC
Sierra LeoneSL
SingaporeSG
Sint MaartenSX
SlovakiaSK
SloveniaSI
Solomon IslandsSB
SomaliaSO
South AfricaZA
South KoreaKR
South SudanSS
SpainES
Sri LankaLK
St. BartsBL
SudanSD
SurinameSR
SwedenSE
SwitzerlandCH
SyriaSY
TaiwanTW
TajikistanTJ
TanzaniaTZ
ThailandTH
The BahamasBH
TogoTG
TongaTO
Trinidad and TobagoTT
TunisiaTN
TurkeyTR
TurkmenistanTM
Turks and Caicos IslandsTC
TuvaluTV
UgandaUG
UkraineUA
United Arab EmiratesAE
United KingdomGB
United StatesUS
UruguayUY
US Virgin IslandsVI
UzbekistanUZ
VanuatuVU
Vatican City (Holy See)VA
VenezuelaVE
VietnamVN
Wallis and FutunaWF
YemenYE
ZambiaZM
ZimbabweZW