--- name: z87:holidays description: 3,391 public holidays across 121 countries (2026–2027). Search by name, country, type. Filter by date range. Track regional vs national holidays with county-level granularity. --- Anonymous: 600 tok/min. Key: `GET https://z87.ai/api/use` → `X-Api-Key` header, 6000 tok/min. On `429`, wait 1s. Search: /search?q=name:christmas+country:GB — field-qualified. Fields: name, local_name, country, type. Filters on /search: from, to, year, nationwide (true=whole country, false=regional only). Country: /country/{code} — all holidays for a country. Filters: from, to, year, type. Date: /date/2026-12-25 — all holidays on a specific date. Filter: country, type. Today: /today?country=US — holidays today in the country's timezone. Requires country. Optional: tz (IANA, e.g. America/Chicago), type. Upcoming: /upcoming?country=JP — next holidays from today. Requires country. Optional: tz, type. Stats: /stats — all country codes, types, date range, counts. nationwide=true means the holiday is observed across the whole country. nationwide=false means it only applies to specific counties/regions (listed in the counties field, e.g. AU-WA, DE-BY, US-MO). Countries (121): AD AL AM AR AT AU AX BA BB BE BG BJ BO BR BS BW BY BZ CA CD CG CH CL CN CO CR CU CY CZ DE DK DO EC EE EG ES FI FO FR GA GB GD GE GG GH GI GL GM GR GT GY HK HN HR HT HU ID IE IM IS IT JE JM JP KE KR KZ LI LS LT LU LV MA MC MD ME MG MK MN MS MT MX MZ NA NE NG NI NL NO NZ PA PE PG PH PL PR PT PY RO RS RU SC SE SG SI SJ SK SM SR SV TN TR UA UG US UY VA VE VN ZA ZW Types: Public, Bank, Observance, Optional, School, Authorities Date range: 2026-01-01 to 2027-12-31 All endpoints accept both **GET with query parameters** and **POST with JSON body**. ## Endpoints ### `https://z87.ai/api/holidays/search` Field-qualified search. Fields: name, local_name, country, type. Filters: from, to, year, nationwide (true=whole country, false=regional only) | Param | Type | Required | Default | |-------|------|----------|---------| | q | string | no | — | | from | string | no | — | | to | string | no | — | | year | u16 | no | — | | nationwide | bool | no | — | | limit | u32 | no | 20 | | offset | u32 | no | 0 | **Example:** `GET https://z87.ai/api/holidays/search?q=name:christmas&limit=3` **Response:** ```json { "holidays": [ { "date": "2026-12-25", "name": "Christmas Day", "local_name": "Nadal", "country_code": "AD", "types": ["Public"], "nationwide": true, "fixed": false }, { "date": "2027-12-25", "name": "Christmas Day", "local_name": "Nadal", "country_code": "AD", "types": ["Public"], "nationwide": true, "fixed": false }, { "date": "2026-12-25", "name": "Christmas Day", "local_name": "Krishtlindjet", "country_code": "AL", "types": ["Public"], "nationwide": true, "fixed": false } ], "total": 294, "limit": 3, "offset": 0 } ``` ### `https://z87.ai/api/holidays/country/{code}` All holidays for a country by ISO-2 code. Filters: from, to, year, type | Param | Type | Required | Default | |-------|------|----------|---------| | from | string | no | — | | to | string | no | — | | year | u16 | no | — | | type | string | no | — | | limit | u32 | no | 20 | | offset | u32 | no | 0 | **Example:** `GET https://z87.ai/api/holidays/country/US?year=2026&limit=3` **Response:** ```json { "country_code": "US", "holidays": [ { "date": "2026-01-01", "name": "New Year's Day", "local_name": "New Year's Day", "country_code": "US", "types": ["Public"], "nationwide": true, "fixed": false }, { "date": "2026-01-19", "name": "Martin Luther King, Jr. Day", "local_name": "Martin Luther King, Jr. Day", "country_code": "US", "types": ["Public"], "nationwide": true, "fixed": false }, { "date": "2026-02-12", "name": "Lincoln's Birthday", "local_name": "Lincoln's Birthday", "country_code": "US", "types": ["Observance"], "nationwide": false, "fixed": false, "counties": ["US-CA", "US-CT", "US-IL", "...6 more"] } ], "total": 16, "limit": 3, "offset": 0 } ``` ### `https://z87.ai/api/holidays/date/{date}` All holidays on a specific date (YYYY-MM-DD). Filter: country, type | Param | Type | Required | Default | |-------|------|----------|---------| | country | string | no | — | | type | string | no | — | | limit | u32 | no | 20 | | offset | u32 | no | 0 | **Example:** `GET https://z87.ai/api/holidays/date/2026-12-25?limit=3` **Response:** ```json { "date": "2026-12-25", "holidays": [ { "date": "2026-12-25", "name": "Christmas Day", "local_name": "Nadal", "country_code": "AD", "types": ["Public"], "nationwide": true, "fixed": false }, { "date": "2026-12-25", "name": "Christmas Day", "local_name": "Krishtlindjet", "country_code": "AL", "types": ["Public"], "nationwide": true, "fixed": false }, { "date": "2026-12-25", "name": "Christmas Day", "local_name": "Navidad", "country_code": "AR", "types": ["Public"], "nationwide": true, "fixed": false } ], "total": 107, "limit": 3, "offset": 0 } ``` ### `https://z87.ai/api/holidays/today` Holidays today for a country. Uses the country's timezone by default. Override with tz (IANA, e.g. Europe/London) | Param | Type | Required | Default | |-------|------|----------|---------| | country | string | **yes** | — | | type | string | no | — | | tz | string | no | country's timezone | | limit | u32 | no | 20 | | offset | u32 | no | 0 | **Example:** `GET https://z87.ai/api/holidays/today?country=US` **Response:** ```json { "date": "2026-05-12", "tz": "America/New_York", "country_code": "US", "holidays": [], "total": 0, "limit": 20, "offset": 0 } ``` ### `https://z87.ai/api/holidays/upcoming` Next holidays from today for a country. Uses the country's timezone by default. Override with tz (IANA, e.g. America/New_York) | Param | Type | Required | Default | |-------|------|----------|---------| | country | string | **yes** | — | | type | string | no | — | | tz | string | no | country's timezone | | limit | u32 | no | 20 | | offset | u32 | no | 0 | **Example:** `GET https://z87.ai/api/holidays/upcoming?country=US&limit=3` **Response:** ```json { "date": "2026-05-12", "tz": "America/New_York", "country_code": "US", "holidays": [ { "date": "2026-05-25", "name": "Memorial Day", "local_name": "Memorial Day", "country_code": "US", "types": ["Public"], "nationwide": true, "fixed": false }, { "date": "2026-06-19", "name": "Juneteenth National Independence Day", "local_name": "Juneteenth National Independence Day", "country_code": "US", "types": ["Public"], "nationwide": true, "fixed": false }, { "date": "2026-07-03", "name": "Independence Day", "local_name": "Independence Day", "country_code": "US", "types": ["Public"], "nationwide": true, "fixed": false } ], "total": 25, "limit": 3, "offset": 0 } ``` ### `https://z87.ai/api/holidays/random` Random holiday No parameters. **Example:** `GET https://z87.ai/api/holidays/random` **Response:** ```json { "holiday": { "date": "2027-08-01", "name": "Parents' Day", "local_name": "Parents' Day", "country_code": "CD", "types": ["Public"], "nationwide": true, "fixed": false } } ``` ### `https://z87.ai/api/holidays/stats` All country codes, types, date range, per-country counts No parameters. **Example:** `GET https://z87.ai/api/holidays/stats` **Response:** ```json { "total": 3391, "countries": [ "AD", "AL", "AM", "AR", "AT", "AU", "AX", "BA", "BB", "BE", "BG", "BJ", "BO", "BR", "BS", "BW", "BY", "BZ", "CA", "CD", "CG", "CH", "CL", "CN", "CO", "CR", "CU", "CY", "CZ", "DE", "DK", "DO", "EC", "EE", "EG", "ES", "FI", "FO", "FR", "GA", "GB", "GD", "GE", "GG", "GH", "GI", "GL", "GM", "GR", "GT", "GY", "HK", "HN", "HR", "HT", "HU", "ID", "IE", "IM", "IS", "IT", "JE", "JM", "JP", "KE", "KR", "KZ", "LI", "LS", "LT", "LU", "LV", "MA", "MC", "MD", "ME", "MG", "MK", "MN", "MS", "MT", "MX", "MZ", "NA", "NE", "NG", "NI", "NL", "NO", "NZ", "PA", "PE", "PG", "PH", "PL", "PR", "PT", "PY", "RO", "RS", "RU", "SC", "SE", "SG", "SI", "SJ", "SK", "SM", "SR", "SV", "TN", "TR", "UA", "UG", "US", "UY", "VA", "VE", "VN", "ZA", "ZW" ], "types": ["Authorities", "Bank", "Observance", "Optional", "Public", "School"], "date_range": {"from": "2026-01-01", "to": "2027-12-31"}, "holidays_per_country": { "KR": 30, "PR": 42, "GT": 26, "LU": 24, "MA": 20, "US": 32, "LS": 22, "EC": 22, "SR": 36, "GE": 34, "PE": 28, "PH": 36, "BR": 30, "ZW": 26, "NL": 22, "VN": 8, "HK": 34, "SI": 42, "TN": 16, "TR": 14, "NZ": 46, "FR": 22, "LT": 28, "BS": 22, "CG": 22, "GB": 27, "MX": 18, "VA": 30, "CR": 22, "BJ": 28, "LV": 32, "PA": 26, "AT": 30, "BZ": 30, "EG": 14, "VE": 68, "FI": 30, "HR": 28, "AD": 28, "CL": 34, "JE": 18, "MT": 28, "RS": 22, "JP": 32, "NO": 24, "GH": 22, "UA": 22, "GM": 18, "GR": 30, "HU": 26, "AL": 28, "IE": 22, "KE": 20, "DK": 28, "CN": 12, "BE": 28, "IS": 32, "HN": 22, "SM": 36, "DE": 38, "BG": 29, "MC": 24, "LI": 42, "DO": 26, "PG": 22, "CY": 34, "IM": 20, "CA": 62, "IT": 28, "NI": 24, "NA": 26, "CO": 36, "BW": 22, "GY": 22, "BB": 24, "PY": 24, "HT": 40, "GL": 32, "KZ": 26, "BA": 30, "JM": 20, "MK": 24, "MG": 20, "SC": 26, "GI": 24, "MD": 32, "SE": 32, "PL": 28, "UY": 30, "NE": 14, "SG": 20, "MN": 20, "CU": 18, "AX": 32, "EE": 24, "NG": 20, "BO": 24, "ES": 64, "GG": 18, "CH": 66, "AU": 51, "AR": 32, "UG": 24, "SK": 30, "GD": 26, "ID": 16, "ME": 40, "FO": 34, "CD": 22, "SJ": 24, "SV": 52, "CZ": 26, "MS": 22, "PT": 34, "RU": 26, "ZA": 24, "RO": 34, "GA": 22, "AM": 28, "BY": 20, "MZ": 18 } } ``` ## License The z87 API code is MIT licensed. Each dataset carries its upstream license: - **holidays**: Holiday data from Nager.Date (https://date.nager.at), licensed under MIT. Country-specific holiday rules sourced from official government publications. --- ## Other z87 Datasets - [chess](https://z87.ai/api/chess/SKILL.md) — 1B+ Lichess games (2000+ Elo, 2013-2026) - [colors](https://z87.ai/api/colors/SKILL.md) — Unified paint color database: ~30K colors across 20+ brands with cross-brand matching via CIEDE2000 perceptual distance, color harmony generation, coordinating color strips, and palette suggestions. - [companies_uk](https://z87.ai/api/companies_uk/SKILL.md) — 5.7M UK companies from Companies House - [countries](https://z87.ai/api/countries/SKILL.md) — 247 countries with 282 indicators (57 static, 225 timeseries) across economics, health, demographics, energy, environment, education, and more - [design](https://z87.ai/api/design/SKILL.md) — 1,003 production-grade frontend designs with HTML, screenshots, prompts, and structured metadata (26 categories, 40 styles, 4K+ tags) - [food](https://z87.ai/api/food/SKILL.md) — Recipes, FDC ingredients, and food products: 13.5K recipes with nutrition, 8K+ FDC ingredients, curated products with Nutri-Score and NOVA ratings. - [gbif](https://z87.ai/api/gbif/SKILL.md) — GBIF Backbone Taxonomy: 7.7 million taxa with full taxonomic hierarchy, synonym resolution, tree navigation, and full-text search across the tree of life. - [gutenberg](https://z87.ai/api/gutenberg/SKILL.md) — 60,000 Project Gutenberg books with chapter-level access, BM25 full-text search, cover art, illustrations, and AI-generated tags (genre, mood, era, locations, five-word summaries). - [home](https://z87.ai/api/home/SKILL.md) — Unified smart home device database - [jokes](https://z87.ai/api/jokes/SKILL.md) — 41,000 jokes from three sources, AI-tagged with category, rating, topics, and offensive score - [manpages](https://z87.ai/api/manpages/SKILL.md) — 142K Linux man pages with AI-generated cheat cards, category tags, use-frequency scores, and plain-english descriptions - [movies](https://z87.ai/api/movies/SKILL.md) — 360K+ movies with 40-axis taste profiles, cast, themes, ratings, and soundtrack data - [mtg](https://z87.ai/api/mtg/SKILL.md) — 29K Magic: The Gathering cards with synergy graph engine, combo detection, and Commander deck builder. - [music](https://z87.ai/api/music/SKILL.md) — 651K artists, 500K+ albums, 1M+ songs from MusicBrainz with genre, country, and member data - [osm](https://z87.ai/api/osm/SKILL.md) — 46M+ OpenStreetMap POIs with Hilbert-curve spatial index and BM25 text search - [podcast](https://z87.ai/api/podcast/SKILL.md) — 1M+ podcasts from PodcastIndex with categories, language, episode counts, popularity scores, and cadence estimates - [restaurants](https://z87.ai/api/restaurants/SKILL.md) — 10K London restaurants with menus, Michelin stars, ingredient category scores (seafood, meat, game, etc.), and capacity data - [solve](https://z87.ai/api/solve/SKILL.md) — Computation engine: symbolic algebra, statistics, regression, finance, graph algorithms, Monte Carlo simulation - [wikipedia](https://z87.ai/api/wikipedia/SKILL.md) — 7.2 million English Wikipedia articles with full markdown content, infoboxes, inter-article links, and geographic coordinates. - [wiktionary](https://z87.ai/api/wiktionary/SKILL.md) — 8M+ Wiktionary entries across 4,000+ languages Full index: [https://z87.ai/api/SKILL.md](https://z87.ai/api/SKILL.md)