Holiday API

Accurate, up-to-date holiday information you can rely on.

Get Your Free API Key
We developers because we are developers.
To retrieve a list of holidays, simply make a GET request to /v1/holidays:
$ curl -G -d country="US" -d year="2018" -d pretty
-d key="__YOUR_API_KEY__"
"https://holidayapi.com/v1/holidays"
Required Parameters
key
string
your API key
country
string
ISO 3166-1 alpha 2 or ISO 3166-2 format (comma separated)
year
number
ISO 8601 format
Optional Parameters
month
number
1 or 2 digit month (1-12)
day
number
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
language
string
ISO 639-1 format
format
string
response format (csv, json [default], php, tsv, yaml and xml)
pretty
boolean
prettifies returned results
Supported Countries and Regions
Want to use this list in your application? Simply make a GET request to /v1/countries
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 (account is delinquent)
403
Forbidden (this API is HTTPS-only)
429
Rate limit exceeded
500
OH NOES!!~! Something is wrong on our end
Sample Response
{
  "status": 200,
  "requests": {
    "used": 700,
    "available": 300,
    "resets": "2019-07-01 00:00:00"
  },
  "holidays": [
    {
      "name": "Independence Day",
      "date": "2015-07-04",
      "observed": "2015-07-03",
      "public": true,
      "country": "US"
    }
  ]
}

Rate Limits

Monthly rate limits vary by plan. Once exceeded the API will return the 429 status code.

We do not throttle accounts with complex per hour / minute / second request limits.

You can easily track your usage via the requests property of the response.

Use the language you love. No judgement here.