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

Get Your API Key

Required Parameters

key
your API key
country
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

BE Belgium
BG Bulgaria
BR Brazil
CA Canada
CZ Czech Republic
DE Germany
ES Spain
FR France
GB United Kingdom
GT Guatemala
HR Croatia
HU Hungary
ID Indonesia
IN India
IT Italy
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!

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 reserved for future use
500
OH NOES!!~! Something is wrong on our end

Response

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

Libraries

Coming Soon!

Go
go-holidayapi
Python
python-holidayapi
Ruby
ruby-holidayapi

Rolled your own? Let us know!

Known Issues

  • Mixed lot of languages. Some countries provide names in the country’s native tongue while others are in English.
  • No support for regional holidays (by way of ISO 3166-2 codes).
  • Only provides holidays that are based on the Gregorian calendar.
  • Not all countries currently support the public flag or date observances.

Future

Currently the primary focus is on improving data consistency for the countries already supported in the system. Secondary focus is on adding new countries and providing official code libraries for various languages to help make development against the API easier.