{"uid":"cap_8VbdNbtNNGw5tCcKQq8g7","slug":"2s-io-calendar-holidays-api-09c9dd29","name":"2s.io Calendar Holidays API","description":"List the official holidays for a country and year, with exact observed dates including substitute days (e.g. a Saturday July 4th observed on Friday). Query: country (ISO 3166-1 alpha-2, 200+ supported), year, optional region (subdivision code like CA for US-California or BY for DE-Bavaria), optional types filter (public, bank, school, optional, observance — comma-separated), optional lang (ISO 639-1) for localized names. Returns one item per holiday: { date (YYYY-MM-DD), name, type, substitute, rule }. Dates are computed from maintained per-country rules — including movable feasts and lunar-calendar holidays — so they stay correct year over year. Use for scheduling, delivery estimates, payment terms, and SLA math.","url":"https://2s.io/api/calendar/holidays","method":"GET","headers":{},"bodySchema":{"type":"object","$schema":"https://json-schema.org/draft/2020-12/schema","required":["input"],"properties":{"input":{"type":"object","required":["type","method","queryParams"],"properties":{"type":{"const":"http"},"method":{"const":"GET"},"queryParams":{"required":["country","year"],"properties":{"lang":{"type":"string","description":"Optional ISO 639-1 language for holiday names."},"year":{"type":"string","description":"Calendar year, e.g. 2026."},"types":{"type":"string","description":"Optional comma-separated filter: public, bank, school, optional, observance."},"region":{"type":"string","description":"Optional subdivision code, e.g. CA (US-California), BY (DE-Bavaria)."},"country":{"type":"string","description":"ISO 3166-1 alpha-2 country code, e.g. US, DE, JP."}}}}}}},"responseSchema":null,"example":{"request":{"input":{"type":"http","method":"GET","queryParams":{"lang":"en","year":"2026","types":"public","country":"US"}}},"response":{"data":{"ok":true,"meta":{"year":2026,"region":null,"country":"US"},"items":[{"date":"2026-01-01","name":"New Year's Day","rule":"01-01 and if sunday then next monday if saturday then previous friday","type":"public","substitute":false},{"date":"2026-01-19","name":"Martin Luther King Jr. Day","rule":"3rd monday in January","type":"public","substitute":false},{"date":"2026-02-16","name":"Washington's Birthday","rule":"3rd monday in February","type":"public","substitute":false},{"date":"2026-05-25","name":"Memorial Day","rule":"monday before 06-01","type":"public","substitute":false},{"date":"2026-06-19","name":"Juneteenth","rule":"06-19 and if sunday then next monday if saturday then previous friday since 2021","type":"public","substitute":false},{"date":"2026-07-03","name":"Independence Day (substitute day)","rule":"07-04 and if sunday then next monday if saturday then previous friday","type":"public","substitute":true},{"date":"2026-07-04","name":"Independence Day","rule":"07-04 and if sunday then next monday if saturday then previous friday","type":"public","substitute":false},{"date":"2026-09-07","name":"Labour Day","rule":"1st monday in September","type":"public","substitute":false},{"date":"2026-10-12","name":"Columbus Day","rule":"2nd monday in October","type":"public","substitute":false},{"date":"2026-11-11","name":"Veterans Day","rule":"11-11","type":"public","substitute":false},{"date":"2026-11-26","name":"Thanksgiving Day","rule":"4th thursday in November","type":"public","substitute":false},{"date":"2026-12-25","name":"Christmas Day","rule":"12-25 and if sunday then next monday if saturday then previous friday","type":"public","substitute":false}],"total":12,"source":{"url":"https://github.com/commenthol/date-holidays","license":"ISC (code) + CC BY 3.0 (holiday data)","provider":"date-holidays rule set (computed locally by 2s.io)"}},"meta":{"cost":{"usd":0.001,"tier":0},"caller":"x402","version":null,"endpoint":"calendar.holidays","settlement":{"txHash":"0x1e3b0edeab46f5c11c0f7e38d6c176469baab1328c83ac7fd36b3036402d52a1","network":"eip155:8453","success":true}}}},"exampleRequest":{"lang":"en","year":"2026","types":"public","country":"US"},"tags":["x402"],"displayCostAmount":"0.001","displayCostAsset":"USDC","priceDynamic":false,"priceHint":null,"priceStatus":"priced","priceSource":"settled","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.0025","per":"call","confidence":"exact"},"accepted":[{"kind":"static","protocol":"x402","network":"base","amountUsd":"0.0025","per":"call","confidence":"exact"}]},"paymentMethods":[{"uid":"pm_Hd1ki_0xph1VkLr2B9pqw","protocol":"x402","methodType":"crypto","chain":"base","mode":"charge","costAmount":"0.0025","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 public, bank, school, and other holidays for a given country and year, with optional region and language filtering.","exampleAgentPrompt":"What are all the public holidays in Japan for 2026, listed in English?","exampleUseCases":null,"resultDescription":"A JSON object containing an array of holiday entries for the requested country and year, each with a date string (YYYY-MM-DD), holiday name, type (public/bank/school/optional/observance), a recurrence rule, and a substitute flag indicating if it's a moved observance. Also includes total count and source attribution (provider, license, URL).","failureModes":["Missing required 'country' or 'year' query parameters returns an error response","Invalid or unsupported ISO 3166-1 country code returns empty results or error","Invalid region/subdivision code may return no regional holidays or an error","Unsupported language code falls back to default language or returns an error","Year out of supported range may return empty or error","Payment not sent or insufficient USDC results in HTTP 402 Payment Required"],"whenToPreferThis":"Use this endpoint when you need structured, machine-readable holiday data for a specific country and year without needing to sign up for an API key. It is especially useful for scheduling automation, date validation, business day calculations, or enriching calendar data across many countries and regions. It covers public, bank, school, and observance holidays with regional subdivision support and multilingual names.","instructions":null,"reviewSummary":null,"reviewSummaryHighlights":null,"reviewSummaryConcerns":null,"reviewSummaryGeneratedAt":null,"activationCount":0,"lastUsedAt":null,"lastSuccessfullyRanAt":null,"lastHealthCheckAt":"2026-09-15T18:59:11.756Z","isFirstParty":false}