# Public Holidays API Worldwide (`conserving_celerytop/public-holidays-api`) Actor

Get public holidays for 250 countries and territories, for any year from 2024 to 2032. One row per holiday with date, English and local name, regional scope and observed days. Data from python-holidays (MIT). Independent tool, not affiliated with python-holidays.

- **URL**: https://apify.com/conserving_celerytop/public-holidays-api.md
- **Developed by:** [Don Mangu](https://apify.com/conserving_celerytop) (community)
- **Features:** Limited permissions
- **Stats:** 2 total users, 1 monthly users, 100.0% runs succeeded, 0 bookmarks
- **User rating**: No ratings yet

## Pricing

from $0.70 / 1,000 holiday records

This Actor is paid per event. You are not charged for the Apify platform usage, but only a fixed price for specific events.
Since this Actor supports Apify Store discounts, the price gets lower the higher subscription plan you have.

Learn more: https://docs.apify.com/actors/running/actors-in-store.md#pay-per-event

## What's an Apify Actor?

An Actor is a serverless cloud program that runs on the Apify platform. It has two run modes.
In Batch mode, an Actor accepts a well-defined JSON input, performs an action which can take anything from a few seconds to a few hours,
and optionally produces a well-defined JSON output, datasets with results, or files in key-value store.
In Standby mode, an Actor provides a web server which can be used as a website, API, or an MCP server.

Apify vocabulary and the platform model are defined once, in the agent quickstart at https://apify.com/agents.md.

## How to integrate an Actor?

If asked about integration, you help developers integrate Actors into their projects.
You adapt to their stack and deliver integrations that are safe, well-documented, and production-ready.

Do not guess an integration path. Every one of them is in the agent quickstart at https://apify.com/agents.md: the Apify MCP server, Agent Skills with the Apify CLI, the JavaScript and Python clients, the REST API, and the account-free path for an agent with no human to sign in. It also carries the rule on stating cost before the first paid run.

For examples already wired to this Actor's own input schema, see the [API](#api) section below.

Each client library has reference documentation the quickstart does not restate: [JavaScript/TypeScript](https://docs.apify.com/api/client/js/docs.md) (`npm install apify-client`) and [Python](https://docs.apify.com/api/client/python/docs.md) (`pip install apify-client`).

# README

Use this public holidays API to list the public holidays of any country for the years 2024 to 2032, for $1.00 per 1,000 holiday rows.

Type a list of countries and years, for example the US, the UK and Germany for 2026, and get one row per holiday: date, weekday, English name, local name, country, and whether the day is nationwide or only in some regions. The data covers 250 countries and territories. Regional holidays carry the state, province or region codes where they apply, so you can ask for "Bavaria" or "Scotland" and get the nationwide days plus the regional ones. The Actor makes no request to any website while it runs. The holiday data ships inside the Actor, so a run is fast and does not fail when an outside service is down. You need no login, no API key and no proxy.

This is an unofficial tool built by an independent developer. It is not affiliated with python-holidays, any government or any calendar service.

### Sample output

One row per holiday. These are real rows from runs on 7 October 2026.

A nationwide replacement day off in the US:

```json
{
  "date": "2026-07-03",
  "year": 2026,
  "weekday": "Friday",
  "countryCode": "US",
  "countryName": "United States",
  "name": "Independence Day (observed)",
  "localName": "Independence Day (observed)",
  "nameLanguage": "en_US",
  "scope": "national",
  "subdivisions": null,
  "isObserved": true,
  "query": "US",
  "source": "python-holidays",
  "sourceVersion": "0.106",
  "licence": "MIT",
  "resultStatus": "ok"
}
```

A regional holiday in Germany:

```json
{
  "date": "2026-06-04",
  "year": 2026,
  "weekday": "Thursday",
  "countryCode": "DE",
  "countryName": "Germany",
  "name": "Corpus Christi",
  "localName": "Fronleichnam",
  "nameLanguage": "en_US",
  "scope": "regional",
  "subdivisions": ["Augsburg", "BW", "BY", "HE", "NW", "RP", "SL"],
  "isObserved": false,
  "query": "Germany",
  "source": "python-holidays",
  "sourceVersion": "0.106",
  "licence": "MIT",
  "resultStatus": "ok"
}
```

### How to get public holidays with this Actor

1. Click **Try for free**. No API key is needed.
2. In **Countries**, enter one country per line, as a two-letter ISO code (US, DE) or an English name (Germany). Leave it empty to get every country.
3. In **Years**, enter a year such as 2026, or a range such as 2026-2028. The data covers 2024 to 2032. If you leave it empty, the Actor uses the current year.
4. Optional: set **From date** and **To date** to cut the list to a window, for example December only.
5. Optional: set **Coverage** to "Nationwide and regional holidays", or enter **Regions** such as US-CA, DE-BY or GB-SCT to get the nationwide days plus the days of those regions.
6. Optional: switch off **Include observed days** if you want only the holidays on their own dates. Set **Holiday name text** to find one holiday, for example christmas.
7. Set **Max results** and click **Start**. Open the **Overview** view and export as JSON, CSV or Excel.

Typical uses:

- Add holiday columns to a payroll, shift or delivery planning sheet.
- Block out holidays in a booking or scheduling tool for each country you serve.
- Check whether a date is a holiday in the market of a customer before you plan a campaign or a call.
- Build a calendar feed for the countries where your team works.

### What you get

| Field | Meaning |
|---|---|
| date, year, weekday | The calendar date, its year and the English weekday name |
| countryCode, countryName | ISO 3166-1 code and English name |
| name, localName | Holiday name in English and in the main language of the country |
| nameLanguage | Language of the name field |
| scope, subdivisions | national, or regional with the codes of the regions where it applies |
| isObserved | true for the replacement day off, false for the holiday itself |
| query | The country text that matched the row |
| source, sourceVersion, licence | Where the data comes from and which version built the files |
| resultStatus | ok, or not_found for a country text that matched nothing |

### Pricing

You pay per holiday row: **$1.00 per 1,000 rows** on the Free plan, with lower prices on paid Apify plans. There is also a small fixed fee of $0.00005 for each run start. A country text that matches no country returns one not_found row and counts as one row.

Cost examples, from real runs on 7 October 2026:

- US, UK and Germany for 2026, nationwide, with observed days: 28 rows. That is $0.028 plus the start fee.
- Every country in the data for 2026, nationwide days only: 3,538 rows. That is $3.54. The run took 2.5 seconds of Actor time on the test machine.
- The largest run you can make, every country for 2024 to 2032 with regional holidays and observed days: 37,929 rows. That is $37.93. The run took 25.9 seconds and peaked at 161 MB of memory.

Set **Max results** to cap your cost. The default is 100 rows.

### Input examples

Nationwide holidays of three countries:

```json
{ "countries": ["US", "GB", "DE"], "years": ["2026"] }
```

Bavaria and Catalonia, with regional days, for two years:

```json
{ "countries": ["Germany", "Spain"], "years": ["2026-2027"], "regions": ["DE-BY", "ES-CT"] }
```

Christmas holidays in December 2026, every country:

```json
{ "years": ["2026"], "fromDate": "2026-12-01", "toDate": "2026-12-31", "searchText": "christmas", "maxResults": 500 }
```

### Run it every year

Holiday dates for the next year are fixed by law or by calendar rules, so most users run the Actor once a year per country list and store the result. You can also schedule a run in Apify and send the dataset to a sheet, a database or a webhook.

### Related Actors

- [Airport Data API](https://apify.com/conserving_celerytop/airport-reference-data-api): Airport reference data: codes, locations and runways.
- [Football Fixtures API](https://apify.com/conserving_celerytop/open-football-fixtures-api): Football fixtures and results from open data.
- [NFL Games API](https://apify.com/conserving_celerytop/nfl-games-api): NFL games, scores and schedules.
- [NWS Weather API](https://apify.com/conserving_celerytop/nws-weather-forecast-alerts-api): Weather forecasts and alerts from weather.gov.
- [UK Visa Sponsor Register Search (Unofficial)](https://apify.com/conserving_celerytop/uk-visa-sponsor-register-api): The UK register of licensed visa sponsors.

### FAQ

**Where does the data come from?**
The files are built from python-holidays, an open source package with an MIT licence that allows commercial use. The Actor does not call a live holiday service. Every row carries the source name, the package version and the licence.

**Is it legal to use and resell this data?**
The MIT licence allows use, copying and sale with the copyright notice kept. Holiday dates are facts. We chose this source because its licence is MIT. We did not use holiday data under a share-alike licence, and we did not use a web service whose terms limit commercial use. This is not legal advice.

**How accurate is it?**
The package is maintained by volunteers and many contributors, and its rules are written from public sources for each country. We compared the output for the UK with the live GOV.UK bank holiday feed for 2024 to 2026: all 106 dates in the feed were in our rows, in England, Wales, Scotland and Northern Ireland. We also checked the US 2026 federal days against the OPM list and the Israel 2026 dates against Hebcal. Still, check dates that depend on moon sightings or on a yearly government decision, such as Islamic holidays, before you rely on them. Do not use the data for legal or payroll decisions without checking the official source.

**What is the difference between nationwide and regional?**
Nationwide holidays apply in the whole country. Regional holidays apply only in some regions, states or provinces, and the subdivisions field lists them. By default you get nationwide rows only. Choose Coverage "Nationwide and regional holidays" for all of them, or enter Regions to get the nationwide rows plus the rows of those regions.

**What are observed days?**
When a holiday falls on a weekend, many countries give a day off on a nearby weekday. Those rows have isObserved set to true and often "(observed)" in the name. The original date stays in the list as a separate row. Switch off Include observed days if you do not want the replacement days.

**Which years can I ask for?**
2024 to 2032. A year outside this range stops the run with a message and no charge.

**Why do some countries return no rows?**
The data has no holidays for some places in some years. For 2026 these are Bouvet Island, Heard Island and McDonald Islands, the British Indian Ocean Territory and Ukraine. Sri Lanka has data for 2024 to 2026 only. The run lists these cases in its status message and in the STATS record, and you pay nothing for them.

**In which language are the names?**
The name field is in English for 210 of the 250 countries. For the other 40 it holds the local text, and nameLanguage tells you which. The localName field is always the main local language of the country.

**What happens if I mistype a country?**
You get one not_found row for that text and the other countries still run. The not_found row counts as one result.

**How fresh is the data?**
The data was built on 7 October 2026 from python-holidays 0.106. It ships inside the Actor as one compressed file, so a run needs no network and starts fast. The STATS record of every run shows the version and the build time. We rebuild the data when the package publishes a new release, and once a year to add the next year.

**What is not included?**
School holidays, bank-only days, half days, trading hours and the names of regions. Subdivisions are shown as codes such as BY or CA.

Data: python-holidays (https://github.com/vacanza/holidays), MIT licence. Disclosure: the developer owns this Actor and has no link to the python-holidays project.

# Actor input Schema

## `countries` (type: `array`):

Enter one country per line, as a two-letter ISO code such as US or DE, or the English country name such as Germany. A country that is not found returns one not_found row. Leave empty to include every country and territory in the data.

## `years` (type: `array`):

Enter one year per line, such as 2026, or a range such as 2026-2028. The data covers 2024 to 2032. Leave empty to use the current year.

## `fromDate` (type: `string`):

Keep only holidays on or after this date, written as YYYY-MM-DD, for example 2026-12-01.

## `toDate` (type: `string`):

Keep only holidays on or before this date, written as YYYY-MM-DD, for example 2026-12-31.

## `coverage` (type: `string`):

Nationwide returns the holidays that apply in the whole country. All adds the holidays that apply only in some regions, states or provinces. If you fill in Regions, this setting is ignored.

## `regions` (type: `array`):

Enter one region code per line, such as US-CA, DE-BY or GB-SCT. You get the nationwide holidays plus the regional holidays that apply in at least one of these regions. Leave empty to ignore regions.

## `includeObserved` (type: `boolean`):

Add the day off that replaces a holiday that falls on a weekend, for example Friday 3 July 2026 for US Independence Day, or the Japanese substitute holidays. These rows have isObserved set to true. Switch off for the holidays on their own dates only.

## `searchText` (type: `string`):

Words that must all appear in the English or the local holiday name, for example christmas or Pessach. Case and accents do not matter.

## `maxResults` (type: `integer`):

Return at most this many rows in total, including not_found rows. Each row returned is one charged result.

## Actor input object example

```json
{
  "countries": [
    "US",
    "GB",
    "DE"
  ],
  "years": [
    "2026"
  ],
  "coverage": "national",
  "includeObserved": true,
  "maxResults": 100
}
```

# Actor output Schema

## `holidays` (type: `string`):

No description

## `stats` (type: `string`):

No description

# API

You can run this Actor programmatically using our API. Below are code examples in JavaScript, Python, and CLI, as well as the OpenAPI specification and MCP server setup.

## JavaScript example

```javascript
import { ApifyClient } from 'apify-client';

// Initialize the ApifyClient with your Apify API token
// Replace the '<YOUR_API_TOKEN>' with your token
const client = new ApifyClient({
    token: '<YOUR_API_TOKEN>',
});

// Prepare Actor input
const input = {
    "countries": [
        "US",
        "GB",
        "DE"
    ],
    "years": [
        "2026"
    ],
    "maxResults": 100
};

// Run the Actor and wait for it to finish
const run = await client.actor("conserving_celerytop/public-holidays-api").call(input);

// Fetch and print Actor results from the run's dataset (if any)
console.log('Results from dataset');
console.log(`💾 Check your data here: https://console.apify.com/storage/datasets/${run.defaultDatasetId}`);
const { items } = await client.dataset(run.defaultDatasetId).listItems();
items.forEach((item) => {
    console.dir(item);
});

// 📚 Want to learn more 📖? Go to → https://docs.apify.com/api/client/js/docs

```

## Python example

```python
from apify_client import ApifyClient

# Initialize the ApifyClient with your Apify API token
# Replace '<YOUR_API_TOKEN>' with your token.
client = ApifyClient("<YOUR_API_TOKEN>")

# Prepare the Actor input
run_input = {
    "countries": [
        "US",
        "GB",
        "DE",
    ],
    "years": ["2026"],
    "maxResults": 100,
}

# Run the Actor and wait for it to finish
run = client.actor("conserving_celerytop/public-holidays-api").call(run_input=run_input)

# Fetch and print Actor results from the run's dataset (if there are any)
print(f"💾 Check your data here: https://console.apify.com/storage/datasets/{run.default_dataset_id}")
for item in client.dataset(run.default_dataset_id).iterate_items():
    print(item)

# 📚 Want to learn more 📖? Go to → https://docs.apify.com/api/client/python/docs/quick-start

```

## CLI example

```bash
echo '{
  "countries": [
    "US",
    "GB",
    "DE"
  ],
  "years": [
    "2026"
  ],
  "maxResults": 100
}' |
apify call conserving_celerytop/public-holidays-api --silent --output-dataset

```

## MCP server setup

```json
{
    "mcpServers": {
        "apify": {
            "type": "http",
            "url": "https://mcp.apify.com/?tools=fetch-actor-details,conserving_celerytop/public-holidays-api"
        }
    }
}
```

The hosted server signs you in with OAuth on first connect, so no API token belongs in this config. Clients without OAuth support can send an `Authorization: Bearer <APIFY_API_TOKEN>` header instead, using a token from API & Integrations in Apify Console (https://console.apify.com/settings/integrations).

## OpenAPI specification

Download the OpenAPI definition: https://api.apify.com/v2/actors/T8lbIWtoT9E7vwBfb/builds/z1w5cHQdu3KIaGTUE/openapi.json