Developer Documentation

Discover the easiest way to enhance your website or application with public holidays and observances.

Up-to-date holiday information, provided by our own API
Just one example of what you can do with Holiday API.
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"
Holidays Parameters

Required Parameters

key
string
Your API key
country
string
For countries, ISO 3166-1 alpha-2 or ISO 3166-1 alpha-3 format.
For subdivisions, ISO 3166-2 format.
Accepts up to 10 comma separated values.
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
search
string
Search holidays by name. Minimum 5 characters.
language
string
ISO 639-1 format (with exceptions).
format
string
Response format (csv, json [default], php, tsv, yaml and xml).
pretty
boolean
Prettifies results to be more human-readable.
Sample Holidays Response
{
    "status": 200,
    "requests": {
        "used": 791,
        "available": 209,
        "resets": "2019-09-01 00:00:00"
    },
    "holidays": [
        {
            "name": "New Year's Day",
            "date": "2015-01-01",
            "observed": "2015-01-01",
            "public": true,
            "country": "US",
            "uuid": "82f78b8a-019e-479e-a19f-99040275f9bf"
        },
        {
            "name": "Mother's Day",
            "date": "2015-05-10",
            "observed": "2015-05-10",
            "public": false,
            "country": "US",
            "uuid": "0746cfc7-6432-4dcc-bc75-dfef56c41086"
        },
        {
            "name": "Independence Day",
            "date": "2015-07-04",
            "observed": "2015-07-03",
            "public": true,
            "country": "US",
            "uuid": "88268759-9b90-468c-804f-b729b8418e7c"
        }
    ]
}
To retrieve a list of countries, simply make a GET request to /v1/countries:
$ curl -G -d pretty
-d key="__YOUR_API_KEY__"
"https://holidayapi.com/v1/countries"
Countries Parameters

Required Parameters

key
string
Your API key
Sample Countries Response
{
    "status": 200,
    "requests": {
        "used": 791,
        "available": 209,
        "resets": "2019-09-01 00:00:00"
    },
    "countries": [
        {
            "code": "ST",
            "name": "Sao Tome and Principe",
            "languages": [
                "pt"
            ],
            "codes": {
                "alpha-2": "ST",
                "alpha-3": "STP",
                "numeric": "678"
            },
            "flag": "https:\/\/www.countryflags.io\/ST\/flat\/64.png",
            "subdivisions": [
                {
                    "code": "ST-P",
                    "name": "Príncipe",
                    "languages": [
                        "pt"
                    ]
                },
                {
                    "code": "ST-S",
                    "name": "São Tomé",
                    "languages": [
                        "pt"
                    ]
                }
            ]
        }
    ]
}
Full list of supported countries and regional subdivisions
To retrieve a list of languages, simply make a GET request to /v1/languages:
$ curl -G -d pretty
-d key="__YOUR_API_KEY__"
"https://holidayapi.com/v1/languages"
Languages Parameters

Required Parameters

key
string
Your API key
Sample Languages Response
{
    "status": 200,
    "requests": {
        "used": 791,
        "available": 209,
        "resets": "2019-09-01 00:00:00"
    },
    "languages": [
        {
            "code": "ar",
            "name": "Arabic"
        },
        {
            "code": "en",
            "name": "English"
        },
        {
            "code": "es",
            "name": "Spanish, Castilian"
        },
        {
            "code": "hi",
            "name": "Hindi"
        },
        {
            "code": "zh",
            "name": "Chinese (Simplified)"
        }
    ]
}
Full list of supported languages
Response Status Codes

Response status codes are returned as both the HTTP status code and as part of the response body.

200
Success! Everything is A-OK.
400
Something is wrong with your request parameters.
401
Unauthorized request. Did you remember your API key?
402
Account is delinquent. Payment is required.
403
Insecure request. HTTPS requests only.
429
Monthly rate limit exceeded.
500
Something went wrong on our end and we've been notified.
Rate Limits

Monthly rate limits vary by plan. Once exceeded the API will return the 429 status code. You can easily track your usage for the current month via the requests property in the response body.

Official SDKs

Community SDKs