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
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
GT Guatemala
HN Honduras
HR Croatia
HU Hungary
ID Indonesia
IE Ireland
IN India
IT Italy
LS Lesotho
LU Luxembourg
MG Madagascar
MQ Martinique
MX Mexico
NL Netherlands
NO Norway
PL Poland
PR Puerto Rico
PT Portugal
RU Russia
SE Sweden
SG Singapore
SI Slovenia
SK Slovakia
UA Ukraine
US United States

Don’t see your country? Get in touch!

Supported Subdivisions

GB-ENG England
GB-NIR Northern Ireland
GB-SCT Scotland
GB-WLS Wales

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.