{"uid":"cap_N9pWMXMtKuoyFJo5VGLke","slug":"holiday-calendar-api-list-public-holidays-by-country-d9b64c14","name":"Holiday Calendar API – List Public Holidays by Country","description":"Official public holidays by country and year, with regional subdivisions, localized names and normalized dates.","url":"https://holidays.use.x402atlas.com/list","method":"GET","headers":{},"bodySchema":{"type":"object","$schema":"https://json-schema.org/draft/2020-12/schema","required":["input"],"properties":{"input":{"type":"object","required":["type","method"],"properties":{"type":{"type":"string","const":"http"},"method":{"enum":["GET"],"type":"string"},"queryParams":{"type":"object","required":["country","year"],"properties":{"year":{"type":"integer","maximum":2030,"minimum":2020,"description":"Calendar year"},"country":{"enum":["AD","AL","AT","BE","BG","BR","BY","CH","CZ","DE","EE","ES","FR","HR","HU","IE","IT","LI","LT","LU","LV","MC","MD","MT","MX","NL","PL","PT","RO","RS","SE","SI","SK","SM","VA","ZA"],"type":"string","description":"Supported ISO 3166-1 alpha-2 country code: AD Andorra; AL Albania; AT Austria; BE Belgium; BG Bulgaria; BR Brazil; BY Belarus; CH Switzerland; CZ Czechia; DE Germany; EE Estonia; ES Spain; FR France; HR Croatia; HU Hungary; IE Ireland; IT Italy; LI Liechtenstein; LT Lithuania; LU Luxembourg; LV Latvia; MC Monaco; MD Moldova; MT Malta; MX Mexico; NL Netherlands; PL Poland; PT Portugal; RO Romania; RS Serbia; SE Sweden; SI Slovenia; SK Slovakia; SM San Marino; VA Vatican City; ZA South Africa."},"language":{"type":"string","pattern":"^[A-Z]{2}$","description":"Optional two-letter ISO 639-1 result language. Defaults to English when available."},"subdivision":{"type":"string","pattern":"^[A-Z]{2}-.+$","maxLength":20,"description":"Optional regional subdivision code beginning with the selected country code, for example DE-BE."}}}},"additionalProperties":false},"output":{"type":"object","required":["type"],"properties":{"type":{"type":"string"},"example":{"type":"object","required":["country","year","queried_at","count","holidays"],"properties":{"year":{"type":"integer"},"count":{"type":"integer"},"country":{"type":"string"},"holidays":{"type":"array","items":{"type":"object","required":["name","start_date","end_date","type","nationwide","subdivisions"],"properties":{"name":{"type":"string","description":"Holiday name in the requested language when available"},"type":{"enum":["Public","Bank","Optional","School","BackToSchool","EndOfLessons"],"type":"string"},"end_date":{"type":"string","format":"date"},"nationwide":{"type":"boolean"},"start_date":{"type":"string","format":"date"},"subdivisions":{"type":"array","items":{"type":"string"}},"regional_scope":{"enum":["National","Regional","Local"],"type":"string"},"temporal_scope":{"enum":["FullDay","HalfDay"],"type":"string"}}}},"language":{"type":"string"},"queried_at":{"type":"string","format":"date-time"},"subdivision":{"type":"string"}}}}}}},"responseSchema":{"type":"json","example":{"year":2026,"count":1,"country":"DE","holidays":[{"name":"New Year's Day","type":"Public","end_date":"2026-01-01","nationwide":true,"start_date":"2026-01-01","subdivisions":[],"regional_scope":"National","temporal_scope":"FullDay"}],"language":"EN","queried_at":"2026-07-27T12:00:00Z","subdivision":"DE-BE"}},"example":null,"exampleRequest":null,"tags":["x402"],"displayCostAmount":"0.005","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.005/call","primary":{"kind":"static","protocol":"x402","network":"base","amountUsd":"0.005","per":"call","confidence":"exact"},"accepted":[{"kind":"static","protocol":"x402","network":"base","amountUsd":"0.005","per":"call","confidence":"exact"}]},"paymentMethods":[{"uid":"pm_hAOyuJH8ATInl0HY4mAnU","protocol":"x402","methodType":"crypto","chain":"base","mode":"charge","costAmount":"0.005","costPer":"request","priority":0,"asset":"0x833589fCD6eDb6E08f4c7C32D4f71b54bdA02913","unit":"request","depositMicros":null,"planRef":null}],"brandName":null,"brandSlug":null,"brandBaseUrl":null,"brandDocsUrl":null,"whatItDoes":"Returns a list of official public holidays for a specified country and year, with optional regional subdivision filtering and localized names.","exampleAgentPrompt":"Can you list all official public holidays in Germany for 2025, including any specific to Bavaria?","exampleUseCases":[{"title":"HR payroll compliance calendar","prompt":"Pull up all official public holidays in France for 2025 so I can set up our payroll calendar — include any regional ones for the Île-de-France subdivision."},{"title":"Travel itinerary planning","prompt":"I'm planning a trip to Italy in 2025 — can you get me the full list of Italian public holidays for that year so I know which days businesses might be closed?"},{"title":"Global SLA scheduling tool","prompt":"We need to know every official public holiday in Brazil for 2025 to configure our support team's SLA blackout dates — please fetch the full list."}],"resultDescription":"A JSON object containing the country code, year, query timestamp, total holiday count, and an array of holiday objects each with the holiday name (in the requested language), start date, end date, type (e.g. public, bank), a nationwide boolean, and applicable subdivision codes.","failureModes":["Unsupported country code returns an error — only 37 specific ISO codes are accepted","Year out of range (below 2020 or above 2030) returns a validation error","Invalid subdivision code format or mismatch with selected country causes rejection","Invalid language code format causes a bad request response","Missing required query parameters (country or year) results in a 400 error"],"whenToPreferThis":"Use this endpoint when you need a full list of all public holidays for a country in a given year — ideal for building calendars, configuring payroll systems, or planning travel. Prefer this over the sibling date-check endpoint when you need the complete holiday schedule rather than checking a single date. Best suited for the 37 supported European, Latin American, and African countries between 2020 and 2030.","instructions":null,"reviewSummary":null,"reviewSummaryHighlights":null,"reviewSummaryConcerns":null,"reviewSummaryGeneratedAt":null,"activationCount":0,"lastUsedAt":null,"lastSuccessfullyRanAt":null,"lastHealthCheckAt":"2026-09-14T00:31:20.489Z","isFirstParty":false}