{"uid":"cap_fe5gTDq50C7jlNRH-DPri","slug":"date-math-public-holidays-by-country-and-year-3bb982c2","name":"Date Math: Public Holidays by Country and Year","description":"Date Math: List public holidays (bank holidays, national holidays) for a country and year: 207 countries, 2000–2050. Use for holiday calendars, office closures and checking if a date is a holiday. Lunar or government-proclaimed dates are rule-based estimates.","url":"https://date-math.datemath.workers.dev/v1/holidays?utm_source=zero.xyz","method":"POST","headers":{},"bodySchema":{"type":"object","properties":{"year":{"type":"integer","maximum":2050,"minimum":2000,"description":"Defaults to the current year"},"country":{"type":"string","example":"US","pattern":"^[A-Za-z]{2}$","description":"ISO 3166-1 alpha-2 country code (207 countries); its public holidays (2000–2050) are excluded from business days"}}},"responseSchema":{"type":"json","example":{"type":"public","year":2026,"count":13,"source":"date-holidays (CC BY 3.0)","country":"PH","holidays":[{"date":"2026-01-01","name":"New Year's Day"}],"country_name":"Philippines"}},"example":null,"exampleRequest":null,"tags":["x402"],"displayCostAmount":"0.001","displayCostAsset":"USDC","priceDynamic":false,"priceHint":null,"priceStatus":"priced","priceSource":"probe","requiresHandshake":false,"reviewCount":0,"rating":{"score":"0.00","successRate":"0.00","reviews":0,"stars":null,"state":"unrated"},"availabilityStatus":"unknown","priceObserved":null,"sessionDeposit":null,"pricing":{"kind":"static","summary":"$0.001/call","primary":{"kind":"static","protocol":"x402","network":"base","amountUsd":"0.001","per":"call","confidence":"exact"},"accepted":[{"kind":"static","protocol":"x402","network":"base","amountUsd":"0.001","per":"call","confidence":"exact"}]},"paymentMethods":[{"uid":"pm_Yse7iuskZ0TieNLVL6pkE","protocol":"x402","methodType":"crypto","chain":"base","mode":"charge","costAmount":"0.001","costPer":"request","priority":0,"asset":"0x833589fCD6eDb6E08f4c7C32D4f71b54bdA02913","unit":"request","depositMicros":null,"planRef":null}],"brandName":null,"brandSlug":null,"brandBaseUrl":null,"brandDocsUrl":null,"whatItDoes":"Returns the list of official public holidays for a given country (207 supported) and year (2000–2050), with dates and holiday names.","exampleAgentPrompt":"What are all the public holidays in the Philippines for 2026? Give me the full list with dates and names.","exampleUseCases":[{"title":"Payroll business-day calculation","prompt":"List all public holidays in Germany for 2025 so I can figure out which days to skip when calculating payroll disbursement dates."},{"title":"International meeting scheduler","prompt":"What are Japan's official public holidays in 2025? I need to avoid scheduling client calls on those days."},{"title":"E-commerce shipping blackout dates","prompt":"Can you get me all the public holidays in Brazil for 2026? I want to block those dates from my store's promised delivery calendar."}],"resultDescription":"A JSON object containing: the country code and full country name, the requested year, the total count of holidays, a list of holiday objects each with an ISO date string and holiday name, and a source attribution (date-holidays CC BY 3.0). Lunar or government-proclaimed dates are rule-based estimates.","failureModes":["Invalid or unsupported country code returns an error — only ISO 3166-1 alpha-2 codes for 207 supported countries are accepted","Year outside the 2000–2050 range returns a validation error","Malformed request body or missing required fields returns a 400-level error","Some holidays based on lunar calendars or government proclamations are estimates and may not reflect last-minute official changes"],"whenToPreferThis":"Choose this endpoint when you need a structured, machine-readable list of official public holidays for a specific country and year, especially for downstream date math like business-day calculations, scheduling, payroll, or shipping. It covers 207 countries and 50 years of data, making it far broader than region-specific or single-country holiday APIs. Pairs naturally with other Date Math sibling endpoints for SLA calculations, business-day arithmetic, or pay-date scheduling.","instructions":null,"reviewSummary":null,"reviewSummaryHighlights":null,"reviewSummaryConcerns":null,"reviewSummaryGeneratedAt":null,"activationCount":0,"lastUsedAt":null,"lastSuccessfullyRanAt":null,"lastHealthCheckAt":"2026-11-21T12:35:13.052Z","isFirstParty":false,"canonicalSlug":"date-math-public-holidays-by-country-and-year-3bb982c2"}