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. 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 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

{
    "mode": "holidays",
    "countryCodes": ["US", "GB", "DE"],
    "years": [2025, 2026]
}

Output example

Each holiday returns structured data with English and local names:

{
    "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:

{
    "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

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

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

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 is available as a tool for AI assistants via the Model Context Protocol (MCP).

Setup for Claude Code

$claude mcp add --transport http apify "https://mcp.apify.com?tools=automation-lab/public-holidays-scraper"

Setup for Claude Desktop, Cursor, or VS Code

{
    "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.

Legality

This actor accesses the free, publicly available Nager.Date API, 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 — country data including population, currencies, languages, and flags
• Worldbank Scraper — World Bank economic indicators and statistics
• Exchange Rate Scraper — currency exchange rates and conversion data