# Public Holidays Finder: 187 Countries, Any Year (`scrapemint/public-holidays-finder`) Actor Get public holidays for any country and year as clean rows: date, holiday name in English and the local language, type, and whether it applies nationwide or only in certain regions. Covers 187 countries, years ahead included. Perfect for payroll, scheduling and delivery apps. No API key needed. - **URL**: https://apify.com/scrapemint/public-holidays-finder.md - **Developed by:** [Ken M](https://apify.com/scrapemint) (community) - **Categories:** Business, Developer tools - **Stats:** 2 total users, 1 monthly users, 100.0% runs succeeded, 0 bookmarks - **User rating**: No ratings yet ## Pricing Pay per usage This Actor is paid per platform usage. The Actor is free to use, and you only pay for the Apify platform usage, which gets cheaper the higher subscription plan you have. Learn more: https://docs.apify.com/platform/actors/running/actors-in-store#pay-per-usage ## 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/docs.md): ```bash npm install apify-client ``` In Python projects, use official [Python client library](https://docs.apify.com/api/client/python/docs.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/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 Finder: 187 Countries, Any Year Get **public holidays for any country and any year** as clean rows: the date, the holiday's name in English and in the local language, its type, and whether it applies nationwide or only in certain regions or states. **187 countries** are covered, and future years work β€” dates are computed from each country's holiday rules. Built for **payroll, HR, delivery and scheduling apps, booking systems and ops teams**. "Don't count holidays as business days" is a requirement in all of them; this turns it into one run instead of a subscription. Planning across markets? One run answers "every holiday in our 12 countries next year." ### What you get for each holiday - **date** and **year** - **name** (English) and **localName** (local language) - **types**: public, bank, school, optional or observance - **nationwide**: true, or false with the **regions** it applies to (US state-level, German LΓ€nder, etc.) - **fixedDate**: whether it falls on the same date every year ### Example output ```json { "country": "KE", "countryName": "Kenya", "year": 2026, "date": "2026-06-01", "name": "Madaraka Day", "localName": "Madaraka Day", "types": ["Public"], "nationwide": true, "fixedDate": true } ```` ### Pricing **$0.002 per holiday row.** Country codes that are not covered are **free**, and the first 2 rows of every run are free. A 10 country, 5 year planning pull (about 600 rows) costs about $1.20 β€” versus $10 to $120 per month for commercial holiday APIs. ### How to run it via API ```bash curl -X POST "https://api.apify.com/v2/acts/scrapemint~public-holidays-finder/run-sync-get-dataset-items?token=YOUR_TOKEN" \ -H "Content-Type: application/json" \ -d '{"countries": ["US", "GB", "KE"], "startYear": 2026, "endYear": 2027}' ``` ### Frequently asked questions **How far ahead can I go?** Years through 2075 are accepted. Holiday dates are computed from each country's official rules, so future years are as reliable as the rules themselves (a government can always announce a one-off holiday). **What about regional holidays?** Rows that only apply in certain states or regions have `nationwide: false` and list the regions, so you can filter to what matters for your locations. **Does it include religious observances that are not days off?** It covers officially recognised holidays per country, with `types` telling you which are full public holidays versus bank, school or optional days. It is not an exhaustive religious calendar. **Where does the data come from?** The open source Nager.Date project, whose holiday rules are maintained publicly and used by thousands of applications. ### More tools from Scrapemint - [Currency Exchange Rates](https://apify.com/scrapemint/currency-exchange-rates-scraper): live and historical rates for 160+ currencies. - [World Economic Indicators](https://apify.com/scrapemint/world-economic-indicators-scraper): GDP, inflation and more for every country. - [Website Change Monitor](https://apify.com/scrapemint/website-change-monitor): watch any page for changes. # Actor input Schema ## `countries` (type: `array`): 2 letter country codes, one per line (US, GB, DE, KE, IN...). 187 countries are covered. ## `startYear` (type: `integer`): First year to fetch. Future years work: holiday dates are computed from each country's rules. ## `endYear` (type: `integer`): Last year to fetch. Leave equal to From year for a single year. Ranges are capped at 11 years per run. ## `maxRows` (type: `integer`): Stop after this many rows in total. ## Actor input object example ```json { "countries": [ "US", "GB", "DE", "KE", "IN" ], "startYear": 2026, "endYear": 2026, "maxRows": 5000 } ``` # 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 = { "countries": [ "US", "GB", "DE", "KE", "IN" ] }; // Run the Actor and wait for it to finish const run = await client.actor("scrapemint/public-holidays-finder").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 = { "countries": [ "US", "GB", "DE", "KE", "IN", ] } # Run the Actor and wait for it to finish run = client.actor("scrapemint/public-holidays-finder").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", "GB", "DE", "KE", "IN" ] }' | apify call scrapemint/public-holidays-finder --silent --output-dataset ``` ## MCP server setup ```json { "mcpServers": { "apify": { "command": "npx", "args": [ "mcp-remote", "https://mcp.apify.com/?tools=scrapemint/public-holidays-finder", "--header", "Authorization: Bearer " ] } } } ``` ## OpenAPI specification ```json { "openapi": "3.0.1", "info": { "title": "Public Holidays Finder: 187 Countries, Any Year", "description": "Get public holidays for any country and year as clean rows: date, holiday name in English and the local language, type, and whether it applies nationwide or only in certain regions. Covers 187 countries, years ahead included. Perfect for payroll, scheduling and delivery apps. No API key needed.", "version": "0.1", "x-build-id": "acadK4Uobzs1cTCi0" }, "servers": [ { "url": "https://api.apify.com/v2" } ], "paths": { "/acts/scrapemint~public-holidays-finder/run-sync-get-dataset-items": { "post": { "operationId": "run-sync-get-dataset-items-scrapemint-public-holidays-finder", "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/scrapemint~public-holidays-finder/runs": { "post": { "operationId": "runs-sync-scrapemint-public-holidays-finder", "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/scrapemint~public-holidays-finder/run-sync": { "post": { "operationId": "run-sync-scrapemint-public-holidays-finder", "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", "required": [ "countries" ], "properties": { "countries": { "title": "Countries", "type": "array", "description": "2 letter country codes, one per line (US, GB, DE, KE, IN...). 187 countries are covered.", "items": { "type": "string" } }, "startYear": { "title": "From year", "minimum": 1975, "maximum": 2075, "type": "integer", "description": "First year to fetch. Future years work: holiday dates are computed from each country's rules.", "default": 2026 }, "endYear": { "title": "To year", "minimum": 1975, "maximum": 2075, "type": "integer", "description": "Last year to fetch. Leave equal to From year for a single year. Ranges are capped at 11 years per run.", "default": 2026 }, "maxRows": { "title": "Max rows", "minimum": 1, "maximum": 50000, "type": "integer", "description": "Stop after this many rows in total.", "default": 5000 } } }, "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 } } } } } } } } } } ```