Public Holidays API for 195+ Countries

Documentation

GET

/api/v1/holidays

Retrieve holiday information for a specific country and date or date range. Use the API key generated from your dashboard to authenticate requests.

Parameters

Name	Type	Description	Required
key	String	API key generated from your dashboard.	Yes
country	String	Name of the country (e.g., "Romania"). Alternatively, use the `code` parameter.	Yes (or `code`)
code	String	Country code (e.g., "RO" for Romania). Use instead of `country`.	Yes (or `country`)
date	String	Single date for which to retrieve holidays. Must match the `format` specified. Defaults to the current date if neither `date` nor `start`/`end` are provided. Cannot be used with `start` or `end`.	No
start	String	Start date of a range for retrieving holidays. Must match the `format` specified and be used with `end`. Cannot be used with `date`. Requires Premium plan (see pricing).	No
end	String	End date of a range for retrieving holidays. Must match the `format` specified and be used with `start`. Cannot be used with `date`. Requires Premium plan (see pricing).	No
format	String	Date format for `date`, `start`, and `end`. Options: `DD-MM-YYYY`, `YYYY-MM-DD`, `YYYY-DD-MM`, `MM-DD-YYYY`, `MM-YYYY-DD`, `DD-YYYY-MM`. Defaults to `DD-MM-YYYY`.	No
output	String	Output format of the response. Options: `json`, `csv`, `xml`. Defaults to `json`.	No

Example Request (Single Date)

GET https://holidaysmap.com/api/v1/holidays?key=940bb8d231cd4eb69d834054251103&country=France&date=01-01-2024&format=DD-MM-YYYY&output=json

Example Response (JSON)

{
    "count": 26,
    "holidays": [
        {
            "name": "New Year's Day",
            "date": "2024-01-01T00:00:00.000Z",
            "is_public": true,
            "country": "France",
            "country_code": "FR"
        }
    ]
}

Example Request (Date Range - Premium)

GET https://holidaysmap.com/api/v1/holidays?key=940bb8d231cd4eb69d834054251103&code=FR&start=01-01-2024&end=06-06-2024&format=DD-MM-YYYY&output=json

Example Response (JSON)

{
    "count": 27,
    "holidays": [
        {
            "name": "New Year's Day",
            "date": "2024-01-01T00:00:00.000Z",
            "is_public": true,
            "country": "France",
            "country_code": "FR"
        },
        {
            "name": "Easter Monday",
            "date": "2024-04-01T00:00:00.000Z",
            "is_public": true,
            "country": "France",
            "country_code": "FR"
        },
        {
            "name": "Labour Day",
            "date": "2024-05-01T00:00:00.000Z",
            "is_public": true,
            "country": "France",
            "country_code": "FR"
        },
        {
            "name": "Victory Day",
            "date": "2024-05-08T00:00:00.000Z",
            "is_public": true,
            "country": "France",
            "country_code": "FR"
        },
        {
            "name": "Ascension Day",
            "date": "2024-05-09T00:00:00.000Z",
            "is_public": true,
            "country": "France",
            "country_code": "FR"
        },
        {
            "name": "Whit Monday",
            "date": "2024-05-20T00:00:00.000Z",
            "is_public": true,
            "country": "France",
            "country_code": "FR"
        }
    ]
}

GET

/api/v1/countries

Retrieve a list of available countries supported by the API.

Parameters

Name	Type	Description	Required
output	String	Output format of the response. Options: `json`, `csv`, `xml`. Defaults to `json`.	No

Example Request

GET https://holidaysmap.com/api/v1/countries?output=json

Example Response (JSON)

{
    "count": 195,
    "countries": [
        {
          "name": "Afghanistan",
          "country_code": "AF",
          "code": "AFG"
        },
        {
          "name": "Albania",
          "country_code": "AL",
          "code": "ALB"
        },
        {
          "name": "Algeria",
          "country_code": "DZ",
          "code": "DZA"
        },
        {
          "name": "Andorra",
          "country_code": "AD",
          "code": "AND"
        },
        ...
    ]
}