# Public Holidays API (`automation-lab/public-holidays-scraper`) Actor Get public holidays for any country and year. Supports 121 countries, long weekends, worldwide holidays, and bulk queries. Uses the free Nager.Date API — no proxy, no API key needed. - **URL**: https://apify.com/automation-lab/public-holidays-scraper.md - **Developed by:** [Stas Persiianenko](https://apify.com/automation-lab) (community) - **Categories:** Other - **Stats:** 6 total users, 1 monthly users, 100.0% runs succeeded, NaN bookmarks - **User rating**: No ratings yet ## Pricing Pay per event 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/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 API Get public holidays for any country and year using the free Nager.Date API. Supports 100+ countries, long weekends, worldwide holidays, and bulk country/year queries. No API key needed. ### What does Public Holidays API do? Public Holidays API fetches structured public holiday data from the [Nager.Date API](https://date.nager.at). Query holidays for specific countries and years, discover long weekends, see upcoming holidays worldwide, or list all 121 supported countries. Results include holiday names in English and local languages, holiday types, and regional coverage. Every country+year combination is queried separately, so you can build bulk datasets across dozens of countries and multiple years in a single run. ### Who is it for? - **HR & payroll teams** managing international employees who need accurate holiday calendars across multiple countries - **Travel and hospitality businesses** planning seasonal promotions around public holidays and long weekends - **E-commerce managers** scheduling sales campaigns and shipping cutoff dates around national holidays - **Financial analysts** accounting for market closure days when modeling trading strategies - **App developers** building calendar features, scheduling tools, or booking systems that need holiday awareness - **Data analysts** studying holiday patterns, comparing countries, or enriching datasets with holiday context ### Why use Public Holidays API? - **121 countries** supported with official public holiday data - **4 query modes** — holidays by country/year, long weekends, next worldwide holidays, supported countries - **Bulk queries** — fetch multiple countries and years in a single run - **Long weekends** — find bridge day opportunities for travel planning - **Local names** — holiday names in both English and the local language - **Holiday types** — public, bank, school, authorities, optional, observance - **Regional coverage** — see whether a holiday is national or limited to specific states/counties - **Zero proxy cost** — uses a free public API, no authentication required - **Fast and cheap** — pure HTTP requests, 256 MB memory, runs complete in seconds ### How to get public holidays data 1. Go to [Public Holidays API](https://apify.com/automation-lab/public-holidays-scraper) on Apify 2. Choose a **Query mode** (Public Holidays, Long Weekends, Next Worldwide, or Available Countries) 3. Enter **Country codes** (e.g., US, GB, DE) and **Years** (e.g., 2025, 2026) 4. Click **Start** and wait for the run to finish 5. Download your data in JSON, CSV, or Excel format ### Input parameters | Parameter | Type | Required | Default | Description | |-----------|------|----------|---------|-------------| | `mode` | string | No | `holidays` | Query mode: `holidays`, `long-weekends`, `next-worldwide`, or `available-countries` | | `countryCodes` | array | No | `["US"]` | ISO 3166-1 alpha-2 country codes (e.g., US, GB, DE, FR, JP) | | `years` | array | No | `[2026]` | Years to fetch holidays for (e.g., 2024, 2025, 2026) | #### Example input ```json { "mode": "holidays", "countryCodes": ["US", "GB", "DE"], "years": [2025, 2026] } ```` ### Output example Each holiday returns structured data with English and local names: ```json { "date": "2026-01-01", "localName": "New Year's Day", "name": "New Year's Day", "countryCode": "US", "fixed": false, "global": true, "counties": null, "launchYear": null, "types": "Public" } ``` Long weekends mode returns: ```json { "startDate": "2026-05-23", "endDate": "2026-05-25", "dayCount": 3, "needBridgeDay": false, "countryCode": "US", "year": 2026 } ``` ### Output fields #### Public Holidays | Field | Type | Description | |-------|------|-------------| | `date` | string | Holiday date in YYYY-MM-DD format | | `name` | string | Holiday name in English | | `localName` | string | Holiday name in the local language | | `countryCode` | string | ISO 3166-1 alpha-2 country code | | `global` | boolean | Whether the holiday is observed nationally | | `types` | string | Holiday types (Public, Bank, School, Authorities, Optional, Observance) | | `counties` | string | Specific states/counties where observed (null if national) | | `fixed` | boolean | Whether the holiday falls on a fixed date every year | | `launchYear` | number | Year the holiday was established (if known) | #### Long Weekends | Field | Type | Description | |-------|------|-------------| | `startDate` | string | Start date of the long weekend | | `endDate` | string | End date of the long weekend | | `dayCount` | number | Total number of days off | | `needBridgeDay` | boolean | Whether a bridge day (vacation day) is needed | | `countryCode` | string | Country code | | `year` | number | Year | ### Query modes explained #### Public Holidays (default) Fetch all official public holidays for specified countries and years. Each country+year combination is queried separately. For example, 3 countries and 2 years = 6 API calls, 6 charge events. #### Long Weekends Find long weekends (3+ consecutive days off) including those requiring a bridge day (taking one vacation day to create a 4-day weekend). Useful for travel planning and HR scheduling. #### Next Public Holidays Worldwide Get the next upcoming public holidays across all supported countries. Returns a snapshot of what holidays are coming up globally. Only charges the start event (no per-country charge). #### Available Countries List all 121 countries supported by the API with their country codes and names. Useful for discovering which countries are available before running holiday queries. ### How much does it cost to get public holiday data? Public Holidays API uses pay-per-event pricing. You only pay for what you use. | Event | Price (Bronze) | |-------|-------| | Run started | $0.005 | | Country-year queried | $0.002 per country+year | #### Cost examples | Scenario | Cost | |----------|------| | US holidays for 2026 (1 country, 1 year) | $0.007 | | US + GB + DE for 2025-2026 (3 countries, 2 years) | $0.017 | | 10 countries for 5 years (50 queries) | $0.105 | | Next worldwide holidays | $0.005 | | Available countries list | $0.005 | Volume discounts are available for higher Apify subscription tiers (Silver, Gold, Platinum, Diamond). ### Tips and best practices - Use ISO 3166-1 alpha-2 codes (2-letter codes like US, GB, DE, FR, JP, BR). The actor validates codes and skips invalid ones gracefully. - Combine multiple countries and years in a single run to minimize start event charges. - Use "Next Worldwide" mode for a quick snapshot of upcoming holidays globally. - Use "Available Countries" mode to discover all 121 supported country codes before building large queries. - Long weekends with `needBridgeDay: true` mean you need to take one vacation day to get the extended weekend. - The API covers years from approximately 2000 to 2035. Older or future years may return errors for some countries. ### Integrations Connect Public Holidays API to your workflow with Apify integrations: - **Google Sheets** — export holiday calendars to spreadsheets for team scheduling - **Zapier / Make** — trigger workflows when new holidays are detected, update calendars automatically - **Webhooks** — get notified when extraction completes, pipe data to your calendar system - **REST API** — call the actor programmatically from any language to keep holiday databases in sync - **Slack / Teams** — post upcoming holiday alerts for remote teams across multiple countries ### Using the Apify API #### Python ```python from apify_client import ApifyClient client = ApifyClient("YOUR_API_TOKEN") run = client.actor("automation-lab/public-holidays-scraper").call( run_input={ "mode": "holidays", "countryCodes": ["US", "GB", "DE"], "years": [2025, 2026] } ) for item in client.dataset(run["defaultDatasetId"]).iterate_items(): print(f"{item['date']} — {item['name']} ({item['countryCode']})") ``` #### Node.js ```javascript import { ApifyClient } from 'apify-client'; const client = new ApifyClient({ token: 'YOUR_API_TOKEN' }); const run = await client.actor('automation-lab/public-holidays-scraper').call({ mode: 'holidays', countryCodes: ['US', 'GB', 'DE'], years: [2025, 2026], }); const { items } = await client.dataset(run.defaultDatasetId).listItems(); items.forEach(item => { console.log(`${item.date} — ${item.name} (${item.countryCode})`); }); ``` #### cURL ```bash curl "https://api.apify.com/v2/acts/automation-lab~public-holidays-scraper/runs" \ -X POST \ -H "Authorization: Bearer YOUR_API_TOKEN" \ -H "Content-Type: application/json" \ -d '{"mode": "holidays", "countryCodes": ["US"], "years": [2026]}' ``` ### Use with AI agents via MCP [Public Holidays API](https://apify.com/automation-lab/public-holidays-scraper) is available as a tool for AI assistants via the [Model Context Protocol (MCP)](https://docs.apify.com/platform/integrations/mcp). #### Setup for Claude Code ```bash claude mcp add --transport http apify "https://mcp.apify.com?tools=automation-lab/public-holidays-scraper" ``` #### Setup for Claude Desktop, Cursor, or VS Code ```json { "mcpServers": { "apify": { "url": "https://mcp.apify.com?tools=automation-lab/public-holidays-scraper" } } } ``` #### Example prompts - "What are the public holidays in Germany for 2026?" - "Find all long weekends in the US and UK for next year" - "Which countries have upcoming holidays this week?" - "Get the holiday calendar for Japan, South Korea, and China for 2025-2026" Learn more in the [Apify MCP documentation](https://docs.apify.com/platform/integrations/mcp). ### Legality This actor accesses the free, publicly available [Nager.Date API](https://date.nager.at), which is designed for programmatic access. No authentication is required, and the data consists of publicly available government holiday schedules. No personal data is collected or processed. ### FAQ **What country codes should I use?** Use ISO 3166-1 alpha-2 codes (2-letter country codes). Examples: US (United States), GB (United Kingdom), DE (Germany), FR (France), JP (Japan), BR (Brazil), IN (India), AU (Australia). Run the "Available Countries" mode to see all 121 supported codes. **I entered a country code but got no results — is it supported?** Not all countries are in the Nager.Date database. Run "Available Countries" mode first to check. The API currently supports 121 countries. Invalid or unsupported codes are skipped gracefully with a warning in the logs. **How far back and forward can I query holidays?** The API generally supports years from approximately 2000 to 2035. Coverage varies by country. If a year is unsupported, the actor logs a warning and continues with other country+year combinations. **What does "needBridgeDay" mean in long weekends?** A bridge day is a regular working day between a holiday and a weekend. When `needBridgeDay` is `true`, taking that one vacation day gives you a 4+ day weekend. When `false`, the long weekend happens naturally without using any vacation days. **Can I get holidays for all 121 countries at once?** Yes. Pass all country codes in the `countryCodes` array. Each country+year is a separate charge event, so 121 countries for 1 year = 121 charge events + 1 start event. ### Other data scrapers - [REST Countries Scraper](https://apify.com/automation-lab/rest-countries-scraper) — country data including population, currencies, languages, and flags - [Worldbank Scraper](https://apify.com/automation-lab/worldbank-scraper) — World Bank economic indicators and statistics - [Exchange Rate Scraper](https://apify.com/automation-lab/exchange-rate-scraper) — currency exchange rates and conversion data # Actor input Schema ## `mode` (type: `string`): Select what to fetch: public holidays for specific countries/years, long weekends, next worldwide holidays, or the list of supported countries. ## `countryCodes` (type: `array`): Enter ISO 3166-1 alpha-2 country codes (e.g., US, GB, DE, FR). Separate multiple codes to query multiple countries in one run. Required for 'Public Holidays' and 'Long Weekends' modes. ## `years` (type: `array`): Enter one or more years to fetch holidays for (e.g., 2024, 2025, 2026). Each country+year combination is queried separately. ## Actor input object example ```json { "mode": "holidays", "countryCodes": [ "US" ], "years": [ 2026 ] } ``` # Actor output Schema ## `overview` (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 '' with your token const client = new ApifyClient({ token: '', }); // Prepare Actor input const input = { "mode": "holidays", "countryCodes": [ "US" ], "years": [ 2026 ] }; // Run the Actor and wait for it to finish const run = await client.actor("automation-lab/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 '' with your token. client = ApifyClient("") # Prepare the Actor input run_input = { "mode": "holidays", "countryCodes": ["US"], "years": [2026], } # Run the Actor and wait for it to finish run = client.actor("automation-lab/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 '{ "mode": "holidays", "countryCodes": [ "US" ], "years": [ 2026 ] }' | apify call automation-lab/public-holidays-scraper --silent --output-dataset ``` ## MCP server setup ```json { "mcpServers": { "apify": { "command": "npx", "args": [ "mcp-remote", "https://mcp.apify.com/?tools=automation-lab/public-holidays-scraper", "--header", "Authorization: Bearer " ] } } } ``` ## OpenAPI specification ```json { "openapi": "3.0.1", "info": { "title": "Public Holidays API", "description": "Get public holidays for any country and year. Supports 121 countries, long weekends, worldwide holidays, and bulk queries. Uses the free Nager.Date API — no proxy, no API key needed.", "version": "0.1", "x-build-id": "p8pJQYrJV2IyhJZVj" }, "servers": [ { "url": "https://api.apify.com/v2" } ], "paths": { "/acts/automation-lab~public-holidays-scraper/run-sync-get-dataset-items": { "post": { "operationId": "run-sync-get-dataset-items-automation-lab-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/automation-lab~public-holidays-scraper/runs": { "post": { "operationId": "runs-sync-automation-lab-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/automation-lab~public-holidays-scraper/run-sync": { "post": { "operationId": "run-sync-automation-lab-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": { "mode": { "title": "📋 Query mode", "enum": [ "holidays", "long-weekends", "next-worldwide", "available-countries" ], "type": "string", "description": "Select what to fetch: public holidays for specific countries/years, long weekends, next worldwide holidays, or the list of supported countries.", "default": "holidays" }, "countryCodes": { "title": "🏳️ Country codes", "type": "array", "description": "Enter ISO 3166-1 alpha-2 country codes (e.g., US, GB, DE, FR). Separate multiple codes to query multiple countries in one run. Required for 'Public Holidays' and 'Long Weekends' modes.", "items": { "type": "string" }, "default": [ "US" ] }, "years": { "title": "📅 Years", "type": "array", "description": "Enter one or more years to fetch holidays for (e.g., 2024, 2025, 2026). Each country+year combination is queried separately.", "items": { "type": "integer" }, "default": [ 2026 ] } } }, "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 } } } } } } } } } } ```