How many countries does the Public Holidays API support?

The API provides public-holiday data for over 100 countries. You can retrieve the complete, authoritative list at any time by calling the /holidays/v1/countries endpoint, which returns each supported country's ISO-3166 alpha-2 code and English name. This is the recommended way to validate a country before making other requests and to populate country dropdowns in your application.

How do I check whether a specific date is a public holiday?

Use the /holidays/v1/is-holiday endpoint with a country code and a date in YYYY-MM-DD form, for example /holidays/v1/is-holiday?country=US&date=2026-07-03. The response includes an is_holiday boolean and a holiday object containing the full matching record (local name, English name, type flags, and regional applicability). When the date is an ordinary day, is_holiday is false and the holiday field is null, which makes it easy to implement business-day and conditional-workflow logic.

What's the difference between the public, range, and next endpoints?

The /holidays/v1/public endpoint returns all holidays for a single calendar year (2000-2100). The /holidays/v1/range endpoint returns holidays within an inclusive from/to window sorted ascending, and the window may span at most 5 years. The /holidays/v1/next endpoint returns the upcoming holidays in the next 365 days. Choose public for full-year calendars, range for arbitrary windows, and next for dashboards and reminders.

How do I tell whether a holiday is nationwide or regional?

Each holiday object includes a global boolean and a counties field. When global is true the holiday applies nationwide and counties is null. When global is false the holiday applies only to the subdivisions listed in counties, which contains ISO-3166-2 codes. Always branch on these fields when regional accuracy matters so that a holiday observed in only one region doesn't incorrectly affect nationwide logic.

How is authentication handled?

Authentication uses a single API key. Pass it as a query parameter, ?apikey=YOUR_API_KEY, or send it in an X-Api-Key header. There is no OAuth flow, no SDK, and no webhooks to configure: just add your key and call. The same key works across every API Codex API.

What happens when I send invalid input or the upstream provider fails?

Inputs are validated before any data is fetched, so bad requests fail fast with a clean 400 and a human-readable message, such as an invalid country code, an out-of-range year, a malformed date, or a 'from' date that is after the 'to' date. A well-formed country code the dataset has no holidays for returns a 404. If the upstream holiday provider is unavailable, the API returns a tidy 502 (504 on timeout) with a short detail field instead of leaking internal errors. Because responses are edge-cached, these upstream issues are rarely visible to end users, and a short retry with backoff handles transient failures gracefully.

Can I limit how many holidays are returned?

Yes. The public, range, next, and countries endpoints accept an optional limit query parameter between 1 and 1000, defaulting to 50. This is useful for previews, paginated UIs, and reducing payload size when you only need the first few results — for example fetching just the next two upcoming holidays for a compact widget.

Worldwide holiday calendars for developers

Public Holidays API

Name: Public Holidays API
Brand: API Codex
SKU: holidays-api

The Public Holidays API gives you accurate, structured public-holiday data for over 100 countries through a handful of dead-simple GET endpoints. Pull every public holiday for a country and year, filter holidays to an arbitrary date range, fetch the upcoming holidays in the next 365 days, or ask a single yes/no question: is this date a public holiday here?

Every response is plain, predictable JSON with the holiday's local name, English name, country, applicable subdivisions, and type flags (Public, Bank, Optional, and more). Built for scheduling, payroll, booking windows, and 'next business day' logic, it is served from the edge and cached for fast, reliable responses.

Get a free API key Read the docs

Free tier included, no credit card required. One key works across every API.

Free calls / month: 1,000
Countries: 100+
Response Time: <80ms
Uptime SLA: 99.9%

Get your free API key

1,000 free calls on the free plan

Key features

Public holidays for any country and calendar year
Date-range filtering across up to 5 years
Upcoming holidays for the next 365 days
Single-date "is it a holiday?" checks
List of all supported countries
Local name, English name, and holiday type flags
Nationwide vs. regional (subdivision) awareness via global and counties fields
Strict input validation with clean 400 errors

Built for

Scheduling and SLA calculations
Payroll and HR systems
"Next business day" logic
Booking and delivery windows
Travel planning applications
Reminder and notification features
Calendar and event apps
Regional observance handling

MCP · for your agent

Hand the Public Holidays API to your agent

Connect Claude, Cursor or any MCP client once, then ask in plain words. Your agent finds this API, reads its docs and makes the call: 1 credit per call, the same as REST, from your team's balance.

Connect your agent

Plan a release freeze

“We ship to the US and Germany. Which public holidays fall between Nov 15 and Jan 10? I'm planning our release freeze.”

list_apis · get_api_docsfree

api_request GET /holidays/v1/range?country=DE&from=2026-11-15&to=2027-01-10 1 cr

Holidays in both countries across the window, merged into one release-freeze calendar.

Explain a late delivery

“A customer asks why their July 3 delivery slipped. Was that a US public holiday?”

list_apis · get_api_docsfree

api_request GET /holidays/v1/is-holiday?country=US&date=2026-07-03 1 cr

Yes: July 3 was the observed Independence Day holiday, which explains the delay.

Staff support around holidays

“Which public holidays are coming up in Brazil? I need to plan support coverage for our São Paulo customers.”

list_apis · get_api_docsfree

api_request GET /holidays/v1/next?country=BR&limit=5 1 cr

The next five public holidays in Brazil with dates and names, for the support rota.

$ claude mcp add --transport http apicodex https://mcp.apicodex.io

Illustrative asks; the calls and prices are real. Claude, Cursor, VS Code and Windsurf setup: mcp.apicodex.io

Try it

Build the request for your data

Edit the parameters below and see the exact request and curl command you'd send. No key required to preview.

GET /holidays/v1/is-holiday

Open in Playground

Parameters

country

date

apikey

Request · HTTP

GET /holidays/v1/is-holiday?country=US&date=2026-07-03&apikey=YOUR_API_KEY HTTP/1.1
Host: api.apicodex.io

Response · JSON 200 OK

{
"country": "US",
"date": "2026-07-03",
"is_holiday": true,
"holiday": {
  "date": "2026-07-03",
  "localName": "Independence Day",
  "name": "Independence Day",
  "countryCode": "US",
  "fixed": false,
  "global": true,
  "counties": null,
  "launchYear": null,
  "types": ["Public"]
}
}

Run it with your key

Documentation

Public Holidays API Documentation

The Public Holidays API delivers worldwide public-holiday data for 100+ countries as clean JSON from the edge. Look up all holidays for a country/year, filter by a date range, fetch the next upcoming holidays, check whether a specific date is a public holiday, and list every supported country. Backed by the open Nager.Date dataset and cached at the edge.

Base URL

url

https://api.apicodex.io/holidays

Authentication

Authenticate by passing your API key as a query parameter, or send it in an X-Api-Key header instead.

headers

GET /holidays/v1/public?country=US&year=2026&apikey=YOUR_API_KEY

Request and response

Illustrative values. Confirm current endpoint behavior, quotas, and data freshness in the API documentation before production use.

request · http

GET /holidays/v1/is-holiday?country=US&date=2026-07-03&apikey=YOUR_API_KEY HTTP/1.1
Host: api.apicodex.io

response · json

{
"country": "US",
"date": "2026-07-03",
"is_holiday": true,
"holiday": {
  "date": "2026-07-03",
  "localName": "Independence Day",
  "name": "Independence Day",
  "countryCode": "US",
  "fixed": false,
  "global": true,
  "counties": null,
  "launchYear": null,
  "types": ["Public"]
}
}

Code examples

cURL

curl --request GET \
  --url 'https://api.apicodex.io/holidays/v1/public?country=US&year=2026&apikey=YOUR_API_KEY'

JavaScript/Node.js

const params = new URLSearchParams({
  country: 'US',
  year: '2026',
  apikey: 'YOUR_API_KEY'
});

const url = `https://api.apicodex.io/holidays/v1/public?${params}`;

try {
  const response = await fetch(url);
  const holidays = await response.json();
  console.log(holidays);
} catch (error) {
  console.error(error);
}

Python

import requests

url = "https://api.apicodex.io/holidays/v1/is-holiday"

querystring = {
    "country": "US",
    "date": "2026-07-03",
    "apikey": "YOUR_API_KEY"
}

response = requests.get(url, params=querystring)

print(response.json())

Available Endpoints

GET /v1/public

All public holidays for a country in a given calendar year (2000-2100). Supports an optional limit (1-1000, default 50).

/v1/public?country=US&year=2026&apikey=YOUR_API_KEY

GET /v1/range

Public holidays within an inclusive date range (from <= date <= to), sorted ascending. The range may span at most 5 years.

/v1/range?country=US&from=2026-06-01&to=2026-12-31&apikey=YOUR_API_KEY

GET /v1/next

Upcoming public holidays for a country within the next 365 days.

/v1/next?country=US&apikey=YOUR_API_KEY

GET /v1/is-holiday

Check whether a specific date is a public holiday. Returns the matching holiday record or null.

/v1/is-holiday?country=US&date=2026-07-03&apikey=YOUR_API_KEY

GET /v1/countries

List all countries supported by the holiday dataset.

/v1/countries?apikey=YOUR_API_KEY

Request Parameters

Required parameters

country ISO-3166 alpha-2 country code, case-insensitive (e.g. US, GB, DE). Required for public, range, next, and is-holiday.
year Calendar year between 2000 and 2100. Required for the public endpoint.
from Inclusive start date (YYYY-MM-DD). Required for the range endpoint.
to Inclusive end date (YYYY-MM-DD), on or after 'from'. Required for the range endpoint.
date Date to check (YYYY-MM-DD, year within 2000-2100). Required for the is-holiday endpoint.
apikey Your API key, passed as a query parameter (or sent as an X-Api-Key header).

Optional parameters

limit Maximum number of items to return (1-1000, default 50). Supported on public, range, next, and countries.

Pricing

Public Holidays API Pricing

This API costs 1 credit per request. Credits are shared across every API on your plan.

Estimate your monthly cost

Drag the slider to match your expected request volume. We'll recommend the cheapest plan that covers it.

Requests per month 10,000

Recommended plan

Starter

$29.99 /month

Credits used

Credits included

Cost per 1K requests

Choose Starter

Free

1,000 credits · ~1,000 requests/mo · 2 rps

All APIs included
No credit card required
Full documentation and examples
MCP server for your AI agents
Up to 5 active API keys

Start for free

Starter

Popular

$29.99 /month

50,000 credits · ~50,000 requests/mo · 10 rps

All APIs included
Email support
Usage dashboard and analytics
MCP server for your AI agents
Up to 5 active API keys

Start with Starter

Pro

$99.99 /month

250,000 credits · ~250,000 requests/mo · 25 rps

All APIs included
Priority support
MCP server for your AI agents
Up to 5 active API keys

Start with Pro

FAQ

Public Holidays API

Key features

Built for

Hand the Public Holidays API to your agent

Plan a release freeze

Explain a late delivery

Staff support around holidays

Build the request for your data

Public Holidays API Documentation

Base URL

Authentication

Request and response

Code examples

Available Endpoints

GET /v1/public

GET /v1/range

GET /v1/next

GET /v1/is-holiday

GET /v1/countries

Request Parameters

Required parameters

Optional parameters

Public Holidays API Pricing

Free

Starter

Pro

Need a different plan?

Frequently asked questions

Related APIs