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
pretty
boolean, prettifies returned results

Supported Countries

AR Argentina
AO Angola
AU Australia
AW Aruba
BE Belgium
BG Bulgaria
BO Bolivia
BR Brazil
CA Canada
CH Switzerland
CN China
CO Colombia
CZ Czech Republic
DE Germany
DK Denmark
EC Ecuador
ES Spain
FR France
GB United Kingdom
GB-ENG England
GB-NIR Northern Ireland
GB-SCT Scotland
GB-WLS Wales
GR Greece
GT Guatemala
HN Honduras
HR Croatia
HU Hungary
ID Indonesia
IE Ireland
IN India
IT Italy
KZ Kazakhstan
LS Lesotho
LU Luxembourg
MG Madagascar
MQ Martinique
MT Malta
MX Mexico
MZ Mozambique
NL Netherlands
NO Norway
PK Pakistan
PH Philippines
PL Poland
PR Puerto Rico
PT Portugal
RE RĂ©union
RU Russia
SC Seychelles
SE Sweden
SG Singapore
SI Slovenia
ST Sao Tome and Principe
SK Slovakia
TR Turkey
UA Ukraine
US United States

Don’t see your country? Get in touch!

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.