Holiday API

Holiday API is a commercial reference-data service that delivers verified public holidays, observances, country and language metadata, and workday calculations for 250 countries and 3,680+ state/province subdivisions in 100+ languages. Operated by Gravity Boulevard, LLC, it exposes five JSON endpoints under https://holidayapi.com/v1/ with official client libraries for Go, Node.js, PHP, Python, Ruby, and Raku.

Holiday API publishes 4 APIs on the APIs.io network, including Countries API, Holidays API, Languages API, and 1 more. Tagged areas include Calendar, Holidays, Public Holidays, Observances, and Reference Data.

The Holiday API catalog on APIs.io includes 1 JSON-LD context and 2 Spectral governance rulesets.

Holiday API’s developer surface includes developer portal, documentation, pricing, signup flow, code examples, and 23 more developer resources.

🌐 Visit website 📡 Source on GitHub

58.4/100 strong ▬ flat Agent 28/100 agent aware Full breakdown ↓
scored 2026-07-28 · rubric v0.6

AccessFreemium

4 APIs 9 Features 7 Use Cases

CalendarHolidaysPublic HolidaysObservancesReference DataCountriesLanguagesWorkdaysBusiness DaysLocalization

Kin Score

Kin Score How this is scored →
scored 2026-07-28 · rubric v0.6

Composite quality — 58.4/100 · strong

Contract Quality 17.2 / 25

Developer Ergonomics 7.4 / 20

Commercial Clarity 14.7 / 20

Operational Transparency 3.4 / 13

Governance 8.3 / 12

Discoverability 7.4 / 10

Agent readiness — 28/100 · agent aware

Machine-Readable Contract 18 / 18

Agentic Access Contract 10 / 10

MCP Server 0 / 12

Machine-Readable Auth 0 / 10

Idempotency 0 / 9

Stable Error Semantics 0 / 8

Request/Response Examples 7 / 7

Rate-Limit Signaling 7 / 7

Typed Event Surface 0 / 6

Agent Skills 0 / 5

Well-Known Catalog 0 / 4

Consent & Bot Identity 0 / 3

A2A Agent Card 0 / 8

Dry-Run / Simulate Mode 0 / 4

Improve this rating by publishing the missing artifacts — every area above can be raised, and the full rubric is at apis.io/rating/. This rating is computed from github.com/api-evangelist/holidays: open an issue to ask a question, or submit a pull request to add artifacts. Want it done for you? Prioritized profiling — $2,500 →

APIs 4

Individual APIs this provider publishes, each with its own machine-readable definition.

Holiday API Countries API

Country metadata, codes, languages, currencies, and subdivisions.

Holiday API Holidays API

Public holidays and observances for countries, states, and provinces.

Holiday API Languages API

Supported languages for retrieving localized holiday names.

Holiday API Workdays API

Working / business day calculations honoring country workweeks and holidays.

Postman Collections 4

Ready-to-run Postman collections for exercising this provider's APIs.

Holiday Countries API

POSTMAN

Holiday Countries Holidays API

POSTMAN

Holiday Countries Languages API

POSTMAN

Holiday Countries Workdays API

POSTMAN

Pricing Plans 1

Published pricing tiers and plan structures.

Holidays Plans Pricing

3 plans

PLANS

Rate Limits 1

Documented rate limits and quota policies.

Holidays Rate Limits

1 limits

RATE LIMITS

FinOps 1

Cost, billing, and metering signals for API financial operations.

Holidays Finops

FINOPS

Features 9

Notable capabilities this provider offers.

Verified Holiday Data

Proprietary holiday generation system continuously verifies holidays for 250 countries.

Subdivision Coverage

3,680 state and province subdivisions on the States & Provinces plan via ISO 3166-2.

100+ Languages

Localized holiday names in over 100 languages via ISO 639-1 codes.

Workday Calculator

Get workdays and count business days between dates honoring country-specific workweeks and holidays.

Historic and Future Dates

Coverage from year 1 through year 2050+ on paid plans.

Multiple Response Formats

JSON, XML, YAML, CSV, TSV, and PHP serialization.

Offline Storage

Unlimited offline caching during active paid subscription; 24-hour window on free tier.

No Velocity Throttling

All plans share a monthly request quota (1M requests/month) with no per-second or per-minute limits.

Five-Nines Uptime

Enterprise-grade infrastructure designed for 99.999% availability.

Scroll for all 9

JSON Schema 5

Standalone JSON Schema definitions for this provider's data models.

Examples 6

Example request and response payloads for these APIs.

AGENTIC

Use Cases 7

What developers build with this provider.

Calendar and Scheduling Apps

Mark public holidays on calendar UIs and prevent scheduling on non-business days.

Business Day SLA Calculation

Compute promised-by dates that honor weekends and country-specific holidays.

HR and Payroll Systems

Determine paid time off, observed holidays, and country-specific leave eligibility.

Localized Marketing Campaigns

Time outreach to align with public holidays in target countries and languages.

E-commerce Fulfillment

Forecast shipping ETAs that respect carrier and destination-country holidays.

Financial Settlement

Adjust transaction value dates and settlement windows around bank holidays.

Global Workforce Management

Coordinate distributed teams across regions with accurate observed-holiday data.

Scroll for all 7

Integrations 4

Pre-built integrations with other platforms and tools.

Spreadsheets

Pull holiday data into Google Sheets / Excel via the JSON, CSV, or TSV format options.

BI Tools

Feed holiday and workday data into Looker, Tableau, or Metabase for calendar dimensions.

Workflow Automation

Trigger Zapier or n8n flows on upcoming/previous holidays per country.

Calendar Platforms

Sync verified holiday data into Google Calendar, Outlook, or iCal feeds.

Resources

Get Started 3

Portal, sign-up, and the first successful call

Portal

Portal

Signup

Signup

Login

Documentation 3

Reference material describing how the API behaves

Documentation

Documentation

OpenAPI

OpenAPI

JSONSchema

JSONSchema

Agent Surfaces 1

MCP servers, agent skills, and machine-readable catalogs

AgenticAccess

AgenticAccess

Design & Contract 4

Pagination, idempotency, versioning, errors, and events

JSONStructure

JSONLD

SpectralRules

Vocabulary

Build 9

SDKs, sample code, and the tooling you integrate with

PostmanWorkspace

PostmanWorkspace

GitHubOrganization

Examples

SDKs

SDKs

SDKs

SDKs

SDKs

SDKs

Scroll for all 9

Access & Security 1

Authentication, authorization, and security posture

DomainSecurity

DomainSecurity

Operate 2

Status, limits, changes, and where to get help

RateLimits

RateLimits

Contact

Contact

Commercial 3

Pricing, plans, and the legal terms of use

Plans

Plans

Pricing

Pricing

TermsOfService

TermsOfService

Company 1

The organization behind the API

Website

Website

Other 1

Properties that don't map to a standard resource type

PublicAPIsListing

PublicAPIsListing

Source (apis.yml)

aid: holidays
name: Holiday API
description: Holiday API is a commercial reference-data service that delivers verified public holidays, observances, country
  and language metadata, and workday calculations for 250 countries and 3,680+ state/province subdivisions in 100+ languages.
  Operated by Gravity Boulevard, LLC, it exposes five JSON endpoints under https://holidayapi.com/v1/ with official client
  libraries for Go, Node.js, PHP, Python, Ruby, and Raku.
accessModel:
  pricing: freemium
  onboarding: unknown
  trial: false
  try_now: false
  public: false
  label: Freemium
  confidence: medium
  source:
  - plans
  generated: '2026-07-22'
  method: derived
image: https://holidayapi.com/images/calendar.svg
url: https://raw.githubusercontent.com/api-evangelist/holidays/main/apis.yml
specificationVersion: '0.20'
created: '2026-05-28'
modified: '2026-05-29'
x-source: public-apis/public-apis
x-category: Calendar
x-tier: 2
x-tier-reason: official OpenAPI definition, official SDKs across 6 languages, commercial provider
tags:
- Calendar
- Holidays
- Public Holidays
- Observances
- Reference Data
- Countries
- Languages
- Workdays
- Business Days
- Localization
apis:
- aid: holidays:holidays-countries-api
  name: Holiday API Countries API
  description: Country metadata, codes, languages, currencies, and subdivisions.
  humanURL: https://holidayapi.com/docs
  baseURL: https://holidayapi.com/v1
  tags:
  - Countries
  properties:
  - type: OpenAPI
    url: openapi/holidays-countries-api-openapi.yml
  - type: Documentation
    url: https://holidayapi.com/docs
  - type: JSONSchema
    url: json-schema/holidays-holiday-schema.json
  - type: JSONStructure
    url: json-structure/holidays-holiday-structure.json
  - type: Examples
    url: examples/holidays-list-holidays-example.json
  - type: JSONLD
    url: json-ld/holidays-context.jsonld
  - type: JSONSchema
    url: json-schema/holidays-country-schema.json
  - type: JSONStructure
    url: json-structure/holidays-country-structure.json
  - type: Examples
    url: examples/holidays-list-countries-example.json
  - type: JSONSchema
    url: json-schema/holidays-language-schema.json
  - type: JSONStructure
    url: json-structure/holidays-language-structure.json
  - type: Examples
    url: examples/holidays-list-languages-example.json
  - type: JSONSchema
    url: json-schema/holidays-workday-schema.json
  - type: JSONStructure
    url: json-structure/holidays-workday-structure.json
  - type: Examples
    url: examples/holidays-get-workday-example.json
  - type: Examples
    url: examples/holidays-get-workdays-example.json
- aid: holidays:holidays-holidays-api
  name: Holiday API Holidays API
  description: Public holidays and observances for countries, states, and provinces.
  humanURL: https://holidayapi.com/docs
  baseURL: https://holidayapi.com/v1
  tags:
  - Holidays
  properties:
  - type: OpenAPI
    url: openapi/holidays-holidays-api-openapi.yml
  - type: Documentation
    url: https://holidayapi.com/docs
  - type: JSONSchema
    url: json-schema/holidays-holiday-schema.json
  - type: JSONStructure
    url: json-structure/holidays-holiday-structure.json
  - type: Examples
    url: examples/holidays-list-holidays-example.json
  - type: JSONLD
    url: json-ld/holidays-context.jsonld
  - type: JSONSchema
    url: json-schema/holidays-country-schema.json
  - type: JSONStructure
    url: json-structure/holidays-country-structure.json
  - type: Examples
    url: examples/holidays-list-countries-example.json
  - type: JSONSchema
    url: json-schema/holidays-language-schema.json
  - type: JSONStructure
    url: json-structure/holidays-language-structure.json
  - type: Examples
    url: examples/holidays-list-languages-example.json
  - type: JSONSchema
    url: json-schema/holidays-workday-schema.json
  - type: JSONStructure
    url: json-structure/holidays-workday-structure.json
  - type: Examples
    url: examples/holidays-get-workday-example.json
  - type: Examples
    url: examples/holidays-get-workdays-example.json
- aid: holidays:holidays-languages-api
  name: Holiday API Languages API
  description: Supported languages for retrieving localized holiday names.
  humanURL: https://holidayapi.com/docs
  baseURL: https://holidayapi.com/v1
  tags:
  - Languages
  properties:
  - type: OpenAPI
    url: openapi/holidays-languages-api-openapi.yml
  - type: Documentation
    url: https://holidayapi.com/docs
  - type: JSONSchema
    url: json-schema/holidays-holiday-schema.json
  - type: JSONStructure
    url: json-structure/holidays-holiday-structure.json
  - type: Examples
    url: examples/holidays-list-holidays-example.json
  - type: JSONLD
    url: json-ld/holidays-context.jsonld
  - type: JSONSchema
    url: json-schema/holidays-country-schema.json
  - type: JSONStructure
    url: json-structure/holidays-country-structure.json
  - type: Examples
    url: examples/holidays-list-countries-example.json
  - type: JSONSchema
    url: json-schema/holidays-language-schema.json
  - type: JSONStructure
    url: json-structure/holidays-language-structure.json
  - type: Examples
    url: examples/holidays-list-languages-example.json
  - type: JSONSchema
    url: json-schema/holidays-workday-schema.json
  - type: JSONStructure
    url: json-structure/holidays-workday-structure.json
  - type: Examples
    url: examples/holidays-get-workday-example.json
  - type: Examples
    url: examples/holidays-get-workdays-example.json
- aid: holidays:holidays-workdays-api
  name: Holiday API Workdays API
  description: Working / business day calculations honoring country workweeks and holidays.
  humanURL: https://holidayapi.com/docs
  baseURL: https://holidayapi.com/v1
  tags:
  - Workdays
  properties:
  - type: OpenAPI
    url: openapi/holidays-workdays-api-openapi.yml
  - type: Documentation
    url: https://holidayapi.com/docs
  - type: JSONSchema
    url: json-schema/holidays-holiday-schema.json
  - type: JSONStructure
    url: json-structure/holidays-holiday-structure.json
  - type: Examples
    url: examples/holidays-list-holidays-example.json
  - type: JSONLD
    url: json-ld/holidays-context.jsonld
  - type: JSONSchema
    url: json-schema/holidays-country-schema.json
  - type: JSONStructure
    url: json-structure/holidays-country-structure.json
  - type: Examples
    url: examples/holidays-list-countries-example.json
  - type: JSONSchema
    url: json-schema/holidays-language-schema.json
  - type: JSONStructure
    url: json-structure/holidays-language-structure.json
  - type: Examples
    url: examples/holidays-list-languages-example.json
  - type: JSONSchema
    url: json-schema/holidays-workday-schema.json
  - type: JSONStructure
    url: json-structure/holidays-workday-structure.json
  - type: Examples
    url: examples/holidays-get-workday-example.json
  - type: Examples
    url: examples/holidays-get-workdays-example.json
common:
- type: PostmanWorkspace
  url: https://www.postman.com/kinlaneapi/holiday-api/overview
- type: AgenticAccess
  url: agentic-access/holidays-agentic-access.yml
- type: DomainSecurity
  url: security/holidays-domain-security.yml
- type: Website
  url: https://holidayapi.com/
- type: Portal
  url: https://holidayapi.com/
- type: Documentation
  url: https://holidayapi.com/docs
- type: OpenAPI
  url: openapi/holidays-api-openapi.yml
- type: JSONSchema
  url: json-schema/holidays-response-schema.json
- type: JSONStructure
  url: json-structure/holidays-response-structure.json
- type: JSONLD
  url: json-ld/holidays-context.jsonld
- type: SpectralRules
  url: rules/holidays-rules.yml
- type: Vocabulary
  url: vocabulary/holidays-vocabulary.yml
- type: Plans
  url: plans/holidays-plans-pricing.yml
- type: RateLimits
  url: rate-limits/holidays-rate-limits.yml
- type: Pricing
  url: https://holidayapi.com/pricing
- type: Signup
  url: https://holidayapi.com/signup
- type: Login
  url: https://holidayapi.com/login
- type: TermsOfService
  url: https://holidayapi.com/terms
- type: Contact
  url: https://holidayapi.com/contact
- type: GitHubOrganization
  url: https://github.com/holidayapi
- type: PublicAPIsListing
  url: https://github.com/public-apis/public-apis
- type: Examples
  url: examples/holidays-error-example.json
- type: SDKs
  url: https://github.com/holidayapi/holidayapi-go
  data:
  - name: Go SDK
    description: Official Go client library (github.com/joshtronic/go-holidayapi mirror).
- type: SDKs
  url: https://github.com/holidayapi/holidayapi-node
  data:
  - name: Node.js / TypeScript SDK
    description: Official Node.js / TypeScript client library.
- type: SDKs
  url: https://github.com/holidayapi/holidayapi-php
  data:
  - name: PHP SDK
    description: Official PHP client library.
- type: SDKs
  url: https://github.com/holidayapi/holidayapi-python
  data:
  - name: Python SDK
    description: Official Python client library.
- type: SDKs
  url: https://github.com/holidayapi/holidayapi-ruby
  data:
  - name: Ruby SDK
    description: Official Ruby client library.
- type: SDKs
  url: https://github.com/holidayapi/holidayapi-raku
  data:
  - name: Raku SDK
    description: Official Raku (Perl 6) client library.
- type: Features
  data:
  - name: Verified Holiday Data
    description: Proprietary holiday generation system continuously verifies holidays for 250 countries.
  - name: Subdivision Coverage
    description: 3,680 state and province subdivisions on the States & Provinces plan via ISO 3166-2.
  - name: 100+ Languages
    description: Localized holiday names in over 100 languages via ISO 639-1 codes.
  - name: Workday Calculator
    description: Get workdays and count business days between dates honoring country-specific workweeks and holidays.
  - name: Historic and Future Dates
    description: Coverage from year 1 through year 2050+ on paid plans.
  - name: Multiple Response Formats
    description: JSON, XML, YAML, CSV, TSV, and PHP serialization.
  - name: Offline Storage
    description: Unlimited offline caching during active paid subscription; 24-hour window on free tier.
  - name: No Velocity Throttling
    description: All plans share a monthly request quota (1M requests/month) with no per-second or per-minute limits.
  - name: Five-Nines Uptime
    description: Enterprise-grade infrastructure designed for 99.999% availability.
- type: UseCases
  data:
  - name: Calendar and Scheduling Apps
    description: Mark public holidays on calendar UIs and prevent scheduling on non-business days.
  - name: Business Day SLA Calculation
    description: Compute promised-by dates that honor weekends and country-specific holidays.
  - name: HR and Payroll Systems
    description: Determine paid time off, observed holidays, and country-specific leave eligibility.
  - name: Localized Marketing Campaigns
    description: Time outreach to align with public holidays in target countries and languages.
  - name: E-commerce Fulfillment
    description: Forecast shipping ETAs that respect carrier and destination-country holidays.
  - name: Financial Settlement
    description: Adjust transaction value dates and settlement windows around bank holidays.
  - name: Global Workforce Management
    description: Coordinate distributed teams across regions with accurate observed-holiday data.
- type: Integrations
  data:
  - name: Spreadsheets
    description: Pull holiday data into Google Sheets / Excel via the JSON, CSV, or TSV format options.
  - name: BI Tools
    description: Feed holiday and workday data into Looker, Tableau, or Metabase for calendar dimensions.
  - name: Workflow Automation
    description: Trigger Zapier or n8n flows on upcoming/previous holidays per country.
  - name: Calendar Platforms
    description: Sync verified holiday data into Google Calendar, Outlook, or iCal feeds.
maintainers:
- FN: Kin Lane
  email: kin@apievangelist.com
  url: https://apievangelist.com

Holiday API

APIs 4

Postman Collections 4

Pricing Plans 1

Rate Limits 1

FinOps 1

Features 9

Verified Holiday Data

Subdivision Coverage

100+ Languages

Workday Calculator

Historic and Future Dates

Multiple Response Formats

Offline Storage

No Velocity Throttling

Five-Nines Uptime

Semantic Vocabularies 1

Spectral Rules 2

JSON Schema 5

JSON Structure 5

Examples 6

Security Posture 1

Agentic Access 1

Use Cases 7

Calendar and Scheduling Apps

Business Day SLA Calculation

HR and Payroll Systems

Localized Marketing Campaigns

E-commerce Fulfillment

Financial Settlement

Global Workforce Management

Integrations 4

Spreadsheets

BI Tools

Workflow Automation

Calendar Platforms

Get Started 3

Documentation 3

Agent Surfaces 1

Design & Contract 4

Build 9

Access & Security 1

Operate 2

Commercial 3

Company 1

Other 1

Source (apis.yml)