# Public Holidays Scraper - Any Country & Year (`benthepythondev/public-holidays-scraper`) Actor

Get official public holidays for any country and year: date, local name, English name, day of week, holiday type, national/regional scope and affected regions. Fast and reliable via the public Nager.Date API. For HR, payroll, scheduling and calendar apps.

- **URL**: https://apify.com/benthepythondev/public-holidays-scraper.md
- **Developed by:** [ben](https://apify.com/benthepythondev) (community)
- **Categories:** Developer tools, Automation, Other
- **Stats:** 2 total users, 1 monthly users, 100.0% runs succeeded, 0 bookmarks
- **User rating**: No ratings yet

## Pricing

from $1.50 / 1,000 results

This Actor is paid per event. You are not charged for the Apify platform usage, but only a fixed price for specific events.

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

## What's an Apify Actor?

Actors are a software tools running on the Apify platform, for all kinds of web data extraction and automation use cases.
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.
Actors are written with capital "A".

## 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.
The best way to integrate Actors is as follows.

In JavaScript/TypeScript projects, use official [JavaScript/TypeScript client](https://docs.apify.com/api/client/js.md):

```bash
npm install apify-client
```

In Python projects, use official [Python client library](https://docs.apify.com/api/client/python.md):

```bash
pip install apify-client
```

In shell scripts, use [Apify CLI](https://docs.apify.com/cli/docs.md):

````bash
# MacOS / Linux
curl -fsSL https://apify.com/install-cli.sh | bash
# Windows
irm https://apify.com/install-cli.ps1 | iex
```bash

In AI frameworks, you might use the [Apify MCP server](https://docs.apify.com/platform/integrations/mcp.md).

If your project is in a different language, use the [REST API](https://docs.apify.com/api/v2.md).

For usage examples, see the [API](#api) section below.

For more details, see Apify documentation as [Markdown index](https://docs.apify.com/llms.txt) and [Markdown full-text](https://docs.apify.com/llms-full.txt).


# README

## 📅 Public Holidays Scraper — Any Country & Year

Get the official **public holidays for any country and year** as clean, structured data — the date, the local-language name, the English name, the day of the week, the holiday type, whether it is national or regional, and exactly which states/counties it applies to. Pull one country or dozens, for a single year or many, in a single run. It is the fastest way to build a reliable holiday calendar for scheduling, payroll and planning.

The actor is powered by the public **Nager.Date API**, which covers 100+ countries, so it is fast and reliable with no browser, no login and no API key. Export to JSON/CSV/Excel, run on a schedule, call via API, or connect to Make, Zapier or n8n.

### 🔎 What is the Public Holidays Scraper?

Knowing which days are official holidays — and where — matters for anything time-sensitive: calculating working days and pay periods, planning deliveries and support coverage, scheduling campaigns, or simply showing the right days off in an app. Maintaining that data by hand across countries is tedious and error-prone.

This actor does it for you. Provide a list of ISO country codes and the years you care about, and it returns every official public holiday as structured rows — with both the native-language name and the English name, a day-of-week label, the holiday type, a national-vs-regional flag, and the list of affected regions for holidays that only apply to certain states or counties. It is ideal for populating HR systems, payroll engines, booking platforms and calendar apps with authoritative, up-to-date holiday data.

#### What data does it extract?

- **Date** — the holiday date in `YYYY-MM-DD`
- **Year** — the year queried
- **Day of week** — Monday…Sunday, computed from the date
- **Local name** — the holiday name in the country's own language
- **Name** — the English name of the holiday
- **Country code** — ISO 3166-1 alpha-2 (e.g. `US`, `DE`, `GB`)
- **Country** — full country name
- **Fixed** — whether the holiday falls on the same calendar date every year
- **Global** — `true` if national, `false` if it applies only to certain regions
- **Counties** — the specific states/counties affected (for regional holidays)
- **Launch year** — the year the holiday was first observed, where known
- **Types** — one or more of Public, Bank, School, Authorities, Optional, Observance

### ⬇️ Input

| Field | Type | Description |
|-------|------|-------------|
| `countries` | array | ISO 3166-1 alpha-2 country codes, e.g. `US`, `DE`, `GB`. One or many. Defaults to `US`. |
| `years` | array | Years to fetch, e.g. `2026`. One or many. Defaults to the current year. |

#### Example input

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

### ⬆️ Output

One clean row per holiday (view as a **table**, or export **JSON / CSV / Excel**):

```json
{
  "date": "2026-01-01",
  "year": 2026,
  "day_of_week": "Thursday",
  "local_name": "New Year's Day",
  "name": "New Year's Day",
  "country_code": "US",
  "country": "United States",
  "fixed": false,
  "global": true,
  "counties": [],
  "launch_year": null,
  "types": ["Public"]
}
```

A regional example — a holiday that only applies to certain German states — returns the affected regions in `counties`:

```json
{
  "date": "2026-01-06",
  "year": 2026,
  "day_of_week": "Tuesday",
  "local_name": "Heilige Drei Könige",
  "name": "Epiphany",
  "country_code": "DE",
  "country": "Germany",
  "fixed": true,
  "global": false,
  "counties": ["DE-BW", "DE-BY", "DE-ST"],
  "launch_year": null,
  "types": ["Public"]
}
```

### 💡 Use cases

- 🗓️ **HR & payroll** — calculate working days, leave entitlements and pay periods correctly for each country and region.
- 🚚 **Logistics & operations** — plan shipping, staffing and support coverage around closures across markets.
- 📆 **Calendar & booking apps** — automatically show local public holidays and block unavailable dates.
- 🤖 **Automation** — feed holiday data into Make/Zapier/n8n workflows, ERPs and scheduling tools.

### ❓ FAQ

**How do I get public holidays for a country?** Add ISO country codes to `countries` and the years to `years`, then Run. You get one structured row per holiday.

**Do I need an API key or login?** No. It uses the public Nager.Date API — just provide country codes and years.

**Which countries are supported?** 100+ countries, addressed by ISO 3166-1 alpha-2 code (e.g. `US`, `DE`, `GB`, `FR`, `JP`).

**Can I fetch multiple countries and years at once?** Yes — pass arrays for both `countries` and `years` and the actor iterates over every combination.

**Does it include regional (state/county) holidays?** Yes. The `global` flag tells you if a holiday is national, and `counties` lists the specific regions a non-national holiday applies to.

**Are the holiday names localized?** Yes — you get both the `local_name` (native language) and the English `name`.

**What is the difference between the holiday types?** `types` can include Public, Bank, School, Authorities, Optional and Observance, so you can filter to only the categories relevant to your use case.

**Can I run it on a schedule or via API?** Yes — schedule it (e.g. once a year to refresh next year's calendar), call it via the API/SDK, or connect it to Make, Zapier or n8n.

**How does pricing work?** Pay per holiday returned — no subscription, no fixed monthly fee.

**Is it legal?** It uses the public Nager.Date API and returns non-personal calendar data. Use it responsibly and in line with the provider's terms.

### 🔗 You might also like

- **[Open-Meteo Weather Scraper](https://apify.com/benthepythondev/open-meteo-weather-scraper)** — global weather forecasts for planning.
- **[Currency Exchange Rates Scraper](https://apify.com/benthepythondev/currency-exchange-rates-scraper)** — live and historical FX rates.
- **[IP Geolocation Scraper](https://apify.com/benthepythondev/ip-geolocation-scraper)** — country, city, timezone & ISP from an IP.
- **[Google News Scraper](https://apify.com/benthepythondev/google-news-scraper)** — headlines by keyword and country.

***

**Keywords:** public holidays scraper, holiday api, bank holidays, national holidays, country holidays, holiday calendar, working days, business days, payroll holidays, hr scheduling, nager date, holidays by country, regional holidays, holiday data, calendar data, days off, statutory holidays, public holiday api, holiday dataset, observances

# Actor input Schema

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

ISO 3166-1 alpha-2 country codes, e.g. 'US', 'DE', 'GB'.

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

Years to fetch, e.g. '2026'. Defaults to the current year.

## Actor input object example

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

# 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"
    ],
    "years": [
        "2026"
    ]
};

// Run the Actor and wait for it to finish
const run = await client.actor("benthepythondev/public-holidays-scraper").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"],
    "years": ["2026"],
}

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

# Fetch and print Actor results from the run's dataset (if there are any)
print("💾 Check your data here: https://console.apify.com/storage/datasets/" + run["defaultDatasetId"])
for item in client.dataset(run["defaultDatasetId"]).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"
  ],
  "years": [
    "2026"
  ]
}' |
apify call benthepythondev/public-holidays-scraper --silent --output-dataset

```

## MCP server setup

```json
{
    "mcpServers": {
        "apify": {
            "command": "npx",
            "args": [
                "mcp-remote",
                "https://mcp.apify.com/?tools=benthepythondev/public-holidays-scraper",
                "--header",
                "Authorization: Bearer <YOUR_API_TOKEN>"
            ]
        }
    }
}

```

## OpenAPI specification

```json
{
    "openapi": "3.0.1",
    "info": {
        "title": "Public Holidays Scraper - Any Country & Year",
        "description": "Get official public holidays for any country and year: date, local name, English name, day of week, holiday type, national/regional scope and affected regions. Fast and reliable via the public Nager.Date API. For HR, payroll, scheduling and calendar apps.",
        "version": "1.0",
        "x-build-id": "VldnfSOYfKZy57s6N"
    },
    "servers": [
        {
            "url": "https://api.apify.com/v2"
        }
    ],
    "paths": {
        "/acts/benthepythondev~public-holidays-scraper/run-sync-get-dataset-items": {
            "post": {
                "operationId": "run-sync-get-dataset-items-benthepythondev-public-holidays-scraper",
                "x-openai-isConsequential": false,
                "summary": "Executes an Actor, waits for its completion, and returns Actor's dataset items in response.",
                "tags": [
                    "Run Actor"
                ],
                "requestBody": {
                    "required": true,
                    "content": {
                        "application/json": {
                            "schema": {
                                "$ref": "#/components/schemas/inputSchema"
                            }
                        }
                    }
                },
                "parameters": [
                    {
                        "name": "token",
                        "in": "query",
                        "required": true,
                        "schema": {
                            "type": "string"
                        },
                        "description": "Enter your Apify token here"
                    }
                ],
                "responses": {
                    "200": {
                        "description": "OK"
                    }
                }
            }
        },
        "/acts/benthepythondev~public-holidays-scraper/runs": {
            "post": {
                "operationId": "runs-sync-benthepythondev-public-holidays-scraper",
                "x-openai-isConsequential": false,
                "summary": "Executes an Actor and returns information about the initiated run in response.",
                "tags": [
                    "Run Actor"
                ],
                "requestBody": {
                    "required": true,
                    "content": {
                        "application/json": {
                            "schema": {
                                "$ref": "#/components/schemas/inputSchema"
                            }
                        }
                    }
                },
                "parameters": [
                    {
                        "name": "token",
                        "in": "query",
                        "required": true,
                        "schema": {
                            "type": "string"
                        },
                        "description": "Enter your Apify token here"
                    }
                ],
                "responses": {
                    "200": {
                        "description": "OK",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "$ref": "#/components/schemas/runsResponseSchema"
                                }
                            }
                        }
                    }
                }
            }
        },
        "/acts/benthepythondev~public-holidays-scraper/run-sync": {
            "post": {
                "operationId": "run-sync-benthepythondev-public-holidays-scraper",
                "x-openai-isConsequential": false,
                "summary": "Executes an Actor, waits for completion, and returns the OUTPUT from Key-value store in response.",
                "tags": [
                    "Run Actor"
                ],
                "requestBody": {
                    "required": true,
                    "content": {
                        "application/json": {
                            "schema": {
                                "$ref": "#/components/schemas/inputSchema"
                            }
                        }
                    }
                },
                "parameters": [
                    {
                        "name": "token",
                        "in": "query",
                        "required": true,
                        "schema": {
                            "type": "string"
                        },
                        "description": "Enter your Apify token here"
                    }
                ],
                "responses": {
                    "200": {
                        "description": "OK"
                    }
                }
            }
        }
    },
    "components": {
        "schemas": {
            "inputSchema": {
                "type": "object",
                "properties": {
                    "countries": {
                        "title": "Country codes",
                        "type": "array",
                        "description": "ISO 3166-1 alpha-2 country codes, e.g. 'US', 'DE', 'GB'.",
                        "items": {
                            "type": "string"
                        }
                    },
                    "years": {
                        "title": "Years",
                        "type": "array",
                        "description": "Years to fetch, e.g. '2026'. Defaults to the current year.",
                        "items": {
                            "type": "string"
                        }
                    }
                }
            },
            "runsResponseSchema": {
                "type": "object",
                "properties": {
                    "data": {
                        "type": "object",
                        "properties": {
                            "id": {
                                "type": "string"
                            },
                            "actId": {
                                "type": "string"
                            },
                            "userId": {
                                "type": "string"
                            },
                            "startedAt": {
                                "type": "string",
                                "format": "date-time",
                                "example": "2025-01-08T00:00:00.000Z"
                            },
                            "finishedAt": {
                                "type": "string",
                                "format": "date-time",
                                "example": "2025-01-08T00:00:00.000Z"
                            },
                            "status": {
                                "type": "string",
                                "example": "READY"
                            },
                            "meta": {
                                "type": "object",
                                "properties": {
                                    "origin": {
                                        "type": "string",
                                        "example": "API"
                                    },
                                    "userAgent": {
                                        "type": "string"
                                    }
                                }
                            },
                            "stats": {
                                "type": "object",
                                "properties": {
                                    "inputBodyLen": {
                                        "type": "integer",
                                        "example": 2000
                                    },
                                    "rebootCount": {
                                        "type": "integer",
                                        "example": 0
                                    },
                                    "restartCount": {
                                        "type": "integer",
                                        "example": 0
                                    },
                                    "resurrectCount": {
                                        "type": "integer",
                                        "example": 0
                                    },
                                    "computeUnits": {
                                        "type": "integer",
                                        "example": 0
                                    }
                                }
                            },
                            "options": {
                                "type": "object",
                                "properties": {
                                    "build": {
                                        "type": "string",
                                        "example": "latest"
                                    },
                                    "timeoutSecs": {
                                        "type": "integer",
                                        "example": 300
                                    },
                                    "memoryMbytes": {
                                        "type": "integer",
                                        "example": 1024
                                    },
                                    "diskMbytes": {
                                        "type": "integer",
                                        "example": 2048
                                    }
                                }
                            },
                            "buildId": {
                                "type": "string"
                            },
                            "defaultKeyValueStoreId": {
                                "type": "string"
                            },
                            "defaultDatasetId": {
                                "type": "string"
                            },
                            "defaultRequestQueueId": {
                                "type": "string"
                            },
                            "buildNumber": {
                                "type": "string",
                                "example": "1.0.0"
                            },
                            "containerUrl": {
                                "type": "string"
                            },
                            "usage": {
                                "type": "object",
                                "properties": {
                                    "ACTOR_COMPUTE_UNITS": {
                                        "type": "integer",
                                        "example": 0
                                    },
                                    "DATASET_READS": {
                                        "type": "integer",
                                        "example": 0
                                    },
                                    "DATASET_WRITES": {
                                        "type": "integer",
                                        "example": 0
                                    },
                                    "KEY_VALUE_STORE_READS": {
                                        "type": "integer",
                                        "example": 0
                                    },
                                    "KEY_VALUE_STORE_WRITES": {
                                        "type": "integer",
                                        "example": 1
                                    },
                                    "KEY_VALUE_STORE_LISTS": {
                                        "type": "integer",
                                        "example": 0
                                    },
                                    "REQUEST_QUEUE_READS": {
                                        "type": "integer",
                                        "example": 0
                                    },
                                    "REQUEST_QUEUE_WRITES": {
                                        "type": "integer",
                                        "example": 0
                                    },
                                    "DATA_TRANSFER_INTERNAL_GBYTES": {
                                        "type": "integer",
                                        "example": 0
                                    },
                                    "DATA_TRANSFER_EXTERNAL_GBYTES": {
                                        "type": "integer",
                                        "example": 0
                                    },
                                    "PROXY_RESIDENTIAL_TRANSFER_GBYTES": {
                                        "type": "integer",
                                        "example": 0
                                    },
                                    "PROXY_SERPS": {
                                        "type": "integer",
                                        "example": 0
                                    }
                                }
                            },
                            "usageTotalUsd": {
                                "type": "number",
                                "example": 0.00005
                            },
                            "usageUsd": {
                                "type": "object",
                                "properties": {
                                    "ACTOR_COMPUTE_UNITS": {
                                        "type": "integer",
                                        "example": 0
                                    },
                                    "DATASET_READS": {
                                        "type": "integer",
                                        "example": 0
                                    },
                                    "DATASET_WRITES": {
                                        "type": "integer",
                                        "example": 0
                                    },
                                    "KEY_VALUE_STORE_READS": {
                                        "type": "integer",
                                        "example": 0
                                    },
                                    "KEY_VALUE_STORE_WRITES": {
                                        "type": "number",
                                        "example": 0.00005
                                    },
                                    "KEY_VALUE_STORE_LISTS": {
                                        "type": "integer",
                                        "example": 0
                                    },
                                    "REQUEST_QUEUE_READS": {
                                        "type": "integer",
                                        "example": 0
                                    },
                                    "REQUEST_QUEUE_WRITES": {
                                        "type": "integer",
                                        "example": 0
                                    },
                                    "DATA_TRANSFER_INTERNAL_GBYTES": {
                                        "type": "integer",
                                        "example": 0
                                    },
                                    "DATA_TRANSFER_EXTERNAL_GBYTES": {
                                        "type": "integer",
                                        "example": 0
                                    },
                                    "PROXY_RESIDENTIAL_TRANSFER_GBYTES": {
                                        "type": "integer",
                                        "example": 0
                                    },
                                    "PROXY_SERPS": {
                                        "type": "integer",
                                        "example": 0
                                    }
                                }
                            }
                        }
                    }
                }
            }
        }
    }
}
```