{ "openapi": "3.1.0", "info": { "title": "Public Holidays API", "version": "1.0.0", "description": "23,786 public holidays for 204 countries from 2020 to 2028, with regional scope and long weekends.\n\nPublic holidays for 204 countries and territories, served from our own database — 23,786 holidays covering 2020 through 2028, sourced from the MIT-licensed Nager.Date project. Each holiday carries its English and local name, nationwide-vs-regional scope (with ISO subdivision codes: Lincoln's Birthday lists US-CA, US-NY...), fixed-date flag and types (Public, Bank, Observance...). Get a country's year (US 2026 correctly shows Independence Day observed on Friday July 3), ask if a given date is a holiday (/holidays/today — 178 countries celebrate December 25), pull the next upcoming holidays for any country, or request computed long weekends (US 2026 has 8 three-day-plus breaks, listed with dates and the anchor holiday). The original /v1/{year}/{code} route still works unchanged, so existing integrations keep running — but responses now come from D1 in milliseconds with multi-year history instead of a third-party proxy call. Scheduling, HR and payroll tools, delivery-date calculators, booking systems and marketing calendars.", "contact": { "name": "Data and APIs", "url": "https://dataandapis.com/contact" }, "termsOfService": "https://dataandapis.com/terms-of-service", "license": { "name": "Data and APIs Terms of Service", "url": "https://dataandapis.com/terms-of-service" }, "x-logo": { "url": "https://dataandapis.com/images/public-holidays.webp" } }, "externalDocs": { "description": "Documentation, live tester and pricing", "url": "https://dataandapis.com/apis/public-holidays" }, "servers": [ { "url": "https://public-holidays.dataandapis.com" } ], "tags": [ { "name": "Events", "description": "Public Holidays API belongs to the Events category of the Data and APIs catalog." } ], "paths": { "/v1/holidays/{country}/{year}": { "get": { "operationId": "countryHolidaysByYear", "summary": "Country Holidays By Year", "description": "Country Holidays By Year endpoint of the Public Holidays API. Costs 1 token per call.", "externalDocs": { "url": "https://dataandapis.com/apis/public-holidays/country-holidays-by-year" }, "parameters": [ { "name": "country", "in": "path", "required": true, "schema": { "type": "string" }, "example": "US" }, { "name": "year", "in": "path", "required": true, "schema": { "type": "string" }, "example": "2026" } ], "responses": { "200": { "description": "Successful response", "content": { "application/json": { "schema": { "type": "object" }, "example": [ { "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", "Bank" ] }, { "date": "2026-01-19", "localName": "Martin Luther King, Jr. Day", "name": "Martin Luther King, Jr. Day", "countryCode": "US", "fixed": false, "global": true, "counties": null, "launchYear": null, "types": [ "Public", "Bank" ] }, { "date": "2026-02-12", "localName": "Lincoln's Birthday", "name": "Lincoln's Birthday", "countryCode": "US", "fixed": false, "global": false, "counties": [ "US-CA", "US-CT", "US-IL", "US-IN", "US-KY", "US-MI", "US-NY", "US-MO", "US-OH" ], "launchYear": null, "types": [ "Observance" ] } ] } } }, "401": { "description": "Missing or invalid API key" }, "402": { "description": "Subscription past due; the response carries a payment_url" }, "429": { "description": "Monthly token allowance exhausted" } }, "security": [ { "ApiKey": [] } ] } }, "/v1/sources": { "get": { "operationId": "dataSources", "summary": "Data Sources", "description": "Data Sources endpoint of the Public Holidays API. Costs 1 token per call.", "externalDocs": { "url": "https://dataandapis.com/apis/public-holidays/data-sources" }, "responses": { "200": { "description": "Successful response", "content": { "application/json": { "schema": { "type": "object" }, "example": { "ok": true, "sources": [ { "slug": "nager-date", "name": "Nager.Date worldwide public holidays", "publisher": "Nager.Date project (Tino Hager and contributors)", "licence": "MIT", "source_url": "https://date.nager.at/", "file_url": "https://date.nager.at/api/v3/PublicHolidays", "cadence": "years 2020-2028; annual re-scrape adds the next year", "record_count": 23786, "retrieved_at": "2026-09-06" } ] } } } }, "401": { "description": "Missing or invalid API key" }, "402": { "description": "Subscription past due; the response carries a payment_url" }, "429": { "description": "Monthly token allowance exhausted" } }, "security": [ { "ApiKey": [] } ] } }, "/v1/holidays/today": { "get": { "operationId": "isItAHoliday", "summary": "Is It A Holiday", "description": "Is It A Holiday endpoint of the Public Holidays API. Costs 1 token per call.", "externalDocs": { "url": "https://dataandapis.com/apis/public-holidays/is-it-a-holiday" }, "parameters": [ { "name": "country", "in": "query", "required": false, "schema": { "type": "string" }, "example": "US" }, { "name": "date", "in": "query", "required": false, "schema": { "type": "string" }, "example": "2026-07-03" } ], "responses": { "200": { "description": "Successful response", "content": { "application/json": { "schema": { "type": "object" }, "example": { "ok": true, "country": "US", "date": "2026-07-03", "is_public_holiday": true, "holidays": [ { "date": "2026-07-03", "localName": "Independence Day", "name": "Independence Day", "countryCode": "US", "fixed": false, "global": true, "counties": null, "launchYear": null, "types": [ "Public", "Bank" ] } ] } } } }, "401": { "description": "Missing or invalid API key" }, "402": { "description": "Subscription past due; the response carries a payment_url" }, "429": { "description": "Monthly token allowance exhausted" } }, "security": [ { "ApiKey": [] } ] } }, "/v1/holidays/long-weekends/{country}/{year}": { "get": { "operationId": "longWeekends", "summary": "Long Weekends", "description": "Long Weekends endpoint of the Public Holidays API. Costs 1 token per call.", "externalDocs": { "url": "https://dataandapis.com/apis/public-holidays/long-weekends" }, "parameters": [ { "name": "country", "in": "path", "required": true, "schema": { "type": "string" }, "example": "US" }, { "name": "year", "in": "path", "required": true, "schema": { "type": "string" }, "example": "2026" } ], "responses": { "200": { "description": "Successful response", "content": { "application/json": { "schema": { "type": "object" }, "example": { "ok": true, "country": "US", "year": 2026, "long_weekends": [ { "start": "2026-01-17", "end": "2026-01-19", "days": 3, "holidays": [ "Martin Luther King, Jr. Day" ] }, { "start": "2026-02-14", "end": "2026-02-16", "days": 3, "holidays": [ "Presidents Day" ] }, { "start": "2026-05-23", "end": "2026-05-25", "days": 3, "holidays": [ "Memorial Day" ] } ] } } } }, "401": { "description": "Missing or invalid API key" }, "402": { "description": "Subscription past due; the response carries a payment_url" }, "429": { "description": "Monthly token allowance exhausted" } }, "security": [ { "ApiKey": [] } ] } }, "/v1/holidays/next": { "get": { "operationId": "nextHolidays", "summary": "Next Holidays", "description": "Next Holidays endpoint of the Public Holidays API. Costs 1 token per call.", "externalDocs": { "url": "https://dataandapis.com/apis/public-holidays/next-holidays" }, "parameters": [ { "name": "count", "in": "query", "required": false, "schema": { "type": "string" }, "example": "5" }, { "name": "country", "in": "query", "required": true, "schema": { "type": "string" }, "example": "MX" } ], "responses": { "200": { "description": "Successful response", "content": { "application/json": { "schema": { "type": "object" }, "example": { "ok": true, "country": "MX", "from": "2026-09-06", "holidays": [ { "date": "2026-09-16", "localName": "Día de la Independencia", "name": "Independence Day", "countryCode": "MX", "fixed": false, "global": true, "counties": null, "launchYear": null, "types": [ "Public" ] }, { "date": "2026-11-16", "localName": "Día de la Revolución", "name": "Revolution Day", "countryCode": "MX", "fixed": false, "global": true, "counties": null, "launchYear": null, "types": [ "Public" ] } ] } } } }, "401": { "description": "Missing or invalid API key" }, "402": { "description": "Subscription past due; the response carries a payment_url" }, "429": { "description": "Monthly token allowance exhausted" } }, "security": [ { "ApiKey": [] } ] } }, "/v1/countries": { "get": { "operationId": "supportedCountries", "summary": "Supported Countries", "description": "Supported Countries endpoint of the Public Holidays API. Costs 1 token per call.", "externalDocs": { "url": "https://dataandapis.com/apis/public-holidays/supported-countries" }, "responses": { "200": { "description": "Successful response", "content": { "application/json": { "schema": { "type": "object" }, "example": { "ok": true, "total": 204, "countries": [ { "code": "AD", "name": "Andorra", "years_from": 2020, "years_to": 2028, "holiday_count": 126 }, { "code": "AL", "name": "Albania", "years_from": 2020, "years_to": 2028, "holiday_count": 119 } ] } } } }, "401": { "description": "Missing or invalid API key" }, "402": { "description": "Subscription past due; the response carries a payment_url" }, "429": { "description": "Monthly token allowance exhausted" } }, "security": [ { "ApiKey": [] } ] } } }, "components": { "securitySchemes": { "ApiKey": { "type": "apiKey", "in": "header", "name": "X-Api-Key", "description": "Create a free key at https://dataandapis.com/sign-up. 500 tokens a month on the Free plan; this API costs 1 token per call." } } }, "security": [ { "ApiKey": [] } ] }