Public Holidays API Documentation

Having trouble with a request? Check the API status to see whether there is an ongoing incident.

Quick start

Create a free account, copy your API key from the dashboard and request the public holidays of any of our 195+ countries in a single call.

cURL

curl "https://holidaysmap.com/api/v1/holidays?key=YOUR_API_KEY&code=RO&date=01-01-2025"

JavaScript

const response = await fetch(
  'https://holidaysmap.com/api/v1/holidays?key=YOUR_API_KEY&code=RO&date=01-01-2025',
);
const { count, holidays } = await response.json();

Python

import requests

response = requests.get(
    "https://holidaysmap.com/api/v1/holidays",
    params={"key": "YOUR_API_KEY", "code": "RO", "date": "01-01-2025"},
)
holidays = response.json()["holidays"]

Java

import java.net.URI;
import java.net.http.HttpClient;
import java.net.http.HttpRequest;
import java.net.http.HttpResponse;

public class Holidays {
    public static void main(String[] args) throws Exception {
        HttpClient client = HttpClient.newHttpClient();
        HttpRequest request = HttpRequest.newBuilder()
            .uri(URI.create("https://holidaysmap.com/api/v1/holidays?key=YOUR_API_KEY&code=RO&date=01-01-2025"))
            .GET()
            .build();
        HttpResponse<String> response =
            client.send(request, HttpResponse.BodyHandlers.ofString());
        System.out.println(response.body());
    }
}

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`. The `date` of every returned holiday uses the same format.	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=YOUR_API_KEY&country=France&date=01-01-2024&format=DD-MM-YYYY&output=json

Example Response (JSON)

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

Example Request (Date Range - Premium)

GET https://holidaysmap.com/api/v1/holidays?key=YOUR_API_KEY&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": "01-01-2024",
            "is_public": true,
            "country": "France",
            "country_code": "FR"
        },
        {
            "name": "Easter Monday",
            "date": "01-04-2024",
            "is_public": true,
            "country": "France",
            "country_code": "FR"
        },
        {
            "name": "Labour Day",
            "date": "01-05-2024",
            "is_public": true,
            "country": "France",
            "country_code": "FR"
        },
        {
            "name": "Victory Day",
            "date": "08-05-2024",
            "is_public": true,
            "country": "France",
            "country_code": "FR"
        },
        {
            "name": "Ascension Day",
            "date": "09-05-2024",
            "is_public": true,
            "country": "France",
            "country_code": "FR"
        },
        {
            "name": "Whit Monday",
            "date": "20-05-2024",
            "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"
        },
        ...
    ]
}

Try Now for Free