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

AU Australia
BE Belgium
BG Bulgaria
BR Brazil
CA Canada
CH Switzerland
CZ Czech Republic
DE Germany
ES Spain
FR France
GB United Kingdom
GT Guatemala
HR Croatia
HU Hungary
ID Indonesia
IN India
IT Italy
LU Luxembourg
MX Mexico
NL Netherlands
NO Norway
PL Poland
PR Puerto Rico
RU Russia
SI Slovenia
SK Slovakia
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?)
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.