Contact

Holiday API

a RESTful service for obtaining holiday data

Basic Usage

To retrieve a list of holidays, simply make a GET request to /v1/holidays

Required Parameters

key
your API key
country
ISO 3166-2 format
year
ISO 8601 format

Optional Parameters

month
1 or 2 digit month (1-12)
day
1 or 2 digit day (1-31 depending on the month)
previous
boolean, return previous holidays based on the date
upcoming
boolean, return upcoming holidays based on the date
public
boolean, return only public holidays
format
string, data return format (csv, json [default], php, tsv, yaml and xml)
pretty
boolean, prettifies returned results

Supported Countries

AO Angola
AT Austria
AU Australia
AW Aruba
AX Åland Islands
BA Bosnia and Herzegovina
BE Belgium
BG Bulgaria
BO Bolivia
BR Brazil
BS The Bahamas
CA Canada
CH Switzerland
CN China
CO Colombia
CR Costa Rica
CU Cuba
CZ Czech Republic
DE Germany
DK Denmark
DO Dominican Republic
EC Ecuador
ES Spain
FI Finland
FR France
FR-A Alsace
GB United Kingdom
GB-ENG England
GB-NIR Northern Ireland
GB-SCT Scotland
GB-WLS Wales
GR Greece
GT Guatemala
HK Hong Kong
HN Honduras
HR Croatia
HU Hungary
ID Indonesia
IE Ireland
IN India
IL Israel
IS Iceland
IT Italy
JP Japan
KZ Kazakhstan
LS Lesotho
LU Luxembourg
MG Madagascar
MQ Martinique
MT Malta
MU Mauritius
MX Mexico
MZ Mozambique
NG Nigeria
NL Netherlands
NO Norway
PE Peru
PK Pakistan
PH Philippines
PL Poland
PR Puerto Rico
PT Portugal
PY Paraguay
RE Réunion
RO Romania
RU Russia
SC Seychelles
SE Sweden
SG Singapore
SI Slovenia
ST Sao Tome and Principe
SK Slovakia
TN Tunisia
TR Turkey
UA Ukraine
US United States
UY Uruguay
VE Venezuela
ZA South Africa
ZW Zimbabwe

don’t see your country? let us know!

Status Codes

200
Success! Everything is A-OK
400
Something is wrong on your end
401
Unauthorized (did you remember your API key?)
402
Payment required (only historical data available is free)
403
Forbidden (this API is HTTPS-only)
429
Rate limit exceeded
500
OH NOES!!~! Something is wrong on our end

Rate Limits

Limits vary by plan, once exceeded the API will return the 429 status code.

Response

{
  "status": 200,
  "holidays": [{
    "name": "Independence Day",
    "date": "2015-07-04"
    "observed": "2015-07-03"
    "public": true,
  }]
}

Client Libraries

We offer libraries for Go, Node.js, PHP, Python and Ruby.

Trusted by Some of Your Favorite Brands