{"openapi":"3.1.0","info":{"title":"Public Holidays API","version":"1.0.0","description":"Public holidays for 120+ countries — by year, the next upcoming holidays for a country, and the list of supported countries. Each holiday includes the date, English and local name, scope (national/regional) and type. Ideal for HR, scheduling and booking systems.","contact":{"name":"PremiumApi","url":"https://www.oanor.com/by/premiumapi"}},"servers":[{"url":"https://api.oanor.com/holidays-api","description":"oanor gateway"}],"tags":[{"name":"Holidays"}],"components":{"securitySchemes":{"oanorKey":{"type":"apiKey","in":"header","name":"x-oanor-key","description":"Get your key at https://www.oanor.com/developer/keys"}}},"security":[{"oanorKey":[]}],"paths":{"/v1/countries":{"get":{"operationId":"get_v1_countries","tags":["Holidays"],"summary":"Supported countries","description":"","parameters":[],"security":[{"oanorKey":[]}],"responses":{"200":{"description":"OK","content":{"application/json":{"example":{"data":{"count":122,"countries":[{"code":"AD","name":"Andorra"},{"code":"AL","name":"Albania"},{"code":"AM","name":"Armenia"},{"code":"AR","name":"Argentina"},{"code":"AT","name":"Austria"},{"code":"AU","name":"Australia"},{"code":"AX","name":"Åland Islands"},{"code":"BA","name":"Bosnia and Herzegovina"},{"code":"BB","name":"Barbados"},{"code":"BD","name":"Bangladesh"},{"code":"BE","name":"Belgium"},{"code":"BG","name":"Bulgaria"},{"code":"BJ","name":"Benin"},{"code":"BO","name":"Bolivia"},{"code":"BR","name":"Brazil"},{"code":"BS","name":"Bahamas"},{"code":"BW","name":"Botswana"},{"code":"BY","name":"Belarus"},{"code":"BZ","name":"Belize"},{"code":"CA","name":"Canada"},{"code":"CD","name":"DR Congo"},{"code":"CG","name":"Congo"},{"code":"CH","name":"Switzerland"},{"code":"CL","name":"Chile"},{"code":"CN","name":"China"},{"code":"CO","name":"Colombia"},{"code":"CR","name":"Costa Rica"},{"code":"CU","name":"Cuba"},{"code":"CY","name":"Cyprus"},{"code":"CZ","name":"Czechia"},{"code":"DE","name":"Germany"},{"code":"DK","name":"Denmark"},{"code":"DO","name":"Dominican Republic"},{"code":"EC","name":"Ecuador"},{"code":"EE","name":"Estonia"},{"code":"EG","name":"Egypt"},{"code":"ES","name":"Spain"},{"code":"FI","name":"Finland"},{"code":"FO","name":"Faroe Islands"},{"code":"FR","name":"France"},{"code":"GA","name":"Gabon"},{"code":"GB","name":"United Kingdom"},{"code":"GD","name":"Grenada"},{"code":"GE","name":"Georgia"},{"code":"GG","name":"Guernsey"},{"code":"GH","name":"Ghana"},{"code":"GI","name":"Gibraltar"},{"code":"GL","name":"Greenland"},{"code":"GM","name":"Gambia"},{"code":"GR","name":"Greece"},{"code":"GT","name":"Guatemala"},{"code":"GY","name":"Guyana"},{"code":"HK","name":"Hong Kong"},{"code":"HN","name":"Honduras"},{"code":"HR","name":"Croatia"},{"code":"HT","name":"Haiti"},{"code":"HU","name":"Hungary"},{"code":"ID","name":"Indonesia"},{"code":"IE","name":"Ireland"},{"code":"IM","name":"Isle of Man"},{"code":"IS","name":"Iceland"},{"code":"IT","name":"Italy"},{"code":"JE","name":"Jersey"},{"code":"JM","name":"Jamaica"},{"code":"JP","name":"Japan"},{"code":"KE","name":"Kenya"},{"code":"KR","name":"South Korea"},{"code":"KZ","name":"Kazakhstan"},{"code":"LI","name":"Liechtenstein"},{"code":"LS","name":"Lesotho"},{"code":"LT","name":"Lithuania"},{"code":"LU","name":"Luxembourg"},{"code":"LV","name":"Latvia"},{"code":"MA","name":"Morocco"},{"code":"MC","name":"Monaco"},{"code":"MD","name":"Moldova"},{"code":"ME","name":"Montenegro"},{"code":"MG","name":"Madagascar"},{"code":"MK","name":"North Macedonia"},{"code":"MN","name":"Mongolia"},{"code":"MS","name":"Montserrat"},{"code":"MT","name":"Malta"},{"code":"MX","name":"Mexico"},{"code":"MZ","name":"Mozambique"},{"code":"NA","name":"Namibia"},{"code":"NE","name":"Niger"},{"code":"NG","name":"Nigeria"},{"code":"NI","name":"Nicaragua"},{"code":"NL","name":"Netherlands"},{"code":"NO","name":"Norway"},{"code":"NZ","name":"New Zealand"},{"code":"PA","name":"Panama"},{"code":"PE","name":"Peru"},{"code":"PG","name":"Papua New Guinea"},{"code":"PH","name":"Philippines"},{"code":"PL","name":"Poland"},{"code":"PR","name":"Puerto Rico"},{"code":"PT","name":"Portugal"},{"code":"PY","name":"Paraguay"},{"code":"RO","name":"Romania"},{"code":"RS","name":"Serbia"},{"code":"RU","name":"Russia"},{"code":"SC","name":"Seychelles"},{"code":"SE","name":"Sweden"},{"code":"SG","name":"Singapore"},{"code":"SI","name":"Slovenia"},{"code":"SJ","name":"Svalbard and Jan Mayen"},{"code":"SK","name":"Slovakia"},{"code":"SM","name":"San Marino"},{"code":"SR","name":"Suriname"},{"code":"SV","name":"El Salvador"},{"code":"TN","name":"Tunisia"},{"code":"TR","name":"Türkiye"},{"code":"UA","name":"Ukraine"},{"code":"UG","name":"Uganda"},{"code":"US","name":"United States"},{"code":"UY","name":"Uruguay"},{"code":"VA","name":"Vatican City"},{"code":"VE","name":"Venezuela"},{"code":"VN","name":"Vietnam"},{"code":"ZA","name":"South Africa"},{"code":"ZW","name":"Zimbabwe"}]},"meta":{"timestamp":"2026-05-30T02:37:24.424Z","request_id":"73bba2dd-2b97-4484-8fc4-f6be928f90a6"},"status":"ok","message":"Countries retrieved successfully","success":true}}}},"401":{"description":"Missing or invalid x-oanor-key header"},"402":{"description":"Active subscription required"},"429":{"description":"Rate-limit or monthly quota reached"},"502":{"description":"Upstream did not respond"}}}},"/v1/holidays":{"get":{"operationId":"get_v1_holidays","tags":["Holidays"],"summary":"Public holidays for a country + year","description":"","parameters":[{"name":"country","in":"query","required":true,"description":"2-letter ISO country code","schema":{"type":"string"},"example":"DE"},{"name":"year","in":"query","required":false,"description":"4-digit year (default current)","schema":{"type":"string"},"example":"2026"}],"security":[{"oanorKey":[]}],"responses":{"200":{"description":"OK","content":{"application/json":{"example":{"data":{"year":2026,"count":19,"country":"DE","holidays":[{"date":"2026-01-01","name":"New Year's Day","types":["Public"],"global":true,"country":"DE","local_name":"Neujahr"},{"date":"2026-01-06","name":"Epiphany","types":["Public"],"global":false,"country":"DE","counties":["DE-BW","DE-BY","DE-ST"],"local_name":"Heilige Drei Könige"},{"date":"2026-03-08","name":"International Women's Day","types":["Public"],"global":false,"country":"DE","counties":["DE-BE","DE-MV"],"local_name":"Internationaler Frauentag"},{"date":"2026-04-03","name":"Good Friday","types":["Public"],"global":true,"country":"DE","local_name":"Karfreitag"},{"date":"2026-04-05","name":"Easter Sunday","types":["Public"],"global":false,"country":"DE","counties":["DE-BB"],"local_name":"Ostersonntag"},{"date":"2026-04-06","name":"Easter Monday","types":["Public"],"global":true,"country":"DE","local_name":"Ostermontag"},{"date":"2026-05-01","name":"Labour Day","types":["Public"],"global":true,"country":"DE","local_name":"Tag der Arbeit"},{"date":"2026-05-14","name":"Ascension Day","types":["Public"],"global":true,"country":"DE","local_name":"Christi Himmelfahrt"},{"date":"2026-05-24","name":"Pentecost","types":["Public"],"global":false,"country":"DE","counties":["DE-BB"],"local_name":"Pfingstsonntag"},{"date":"2026-05-25","name":"Whit Monday","types":["Public"],"global":true,"country":"DE","local_name":"Pfingstmontag"},{"date":"2026-06-04","name":"Corpus Christi","types":["Public"],"global":false,"country":"DE","counties":["DE-BW","DE-BY","DE-HE","DE-NW","DE-RP","DE-SL"],"local_name":"Fronleichnam"},{"date":"2026-08-15","name":"Assumption Day","types":["Public"],"global":false,"country":"DE","counties":["DE-SL"],"local_name":"Mariä Himmelfahrt"},{"date":"2026-09-20","name":"World Children's Day","types":["Public"],"global":false,"country":"DE","counties":["DE-TH"],"local_name":"Weltkindertag"},{"date":"2026-10-03","name":"German Unity Day","types":["Public"],"global":true,"country":"DE","local_name":"Tag der Deutschen Einheit"},{"date":"2026-10-31","name":"Reformation Day","types":["Public"],"global":false,"country":"DE","counties":["DE-BB","DE-MV","DE-SN","DE-ST","DE-TH","DE-HB","DE-HH","DE-NI","DE-SH"],"local_name":"Reformationstag"},{"date":"2026-11-01","name":"All Saints' Day","types":["Public"],"global":false,"country":"DE","counties":["DE-BW","DE-BY","DE-NW","DE-RP","DE-SL"],"local_name":"Allerheiligen"},{"date":"2026-11-18","name":"Repentance and Prayer Day","types":["Public"],"global":false,"country":"DE","counties":["DE-SN"],"local_name":"Buß- und Bettag"},{"date":"2026-12-25","name":"Christmas Day","types":["Public"],"global":true,"country":"DE","local_name":"Erster Weihnachtstag"},{"date":"2026-12-26","name":"St. Stephen's Day","types":["Public"],"global":true,"country":"DE","local_name":"Zweiter Weihnachtstag"}]},"meta":{"timestamp":"2026-05-30T02:37:24.826Z","request_id":"398913a1-0498-49ae-956a-92655810c601"},"status":"ok","message":"Holidays retrieved successfully","success":true}}}},"401":{"description":"Missing or invalid x-oanor-key header"},"402":{"description":"Active subscription required"},"429":{"description":"Rate-limit or monthly quota reached"},"502":{"description":"Upstream did not respond"}}}},"/v1/next":{"get":{"operationId":"get_v1_next","tags":["Holidays"],"summary":"Next upcoming holidays","description":"","parameters":[{"name":"country","in":"query","required":true,"description":"2-letter ISO country code","schema":{"type":"string"},"example":"US"}],"security":[{"oanorKey":[]}],"responses":{"200":{"description":"OK","content":{"application/json":{"example":{"data":{"count":12,"country":"US","holidays":[{"date":"2026-06-19","name":"Juneteenth National Independence Day","types":["Public","Bank"],"global":true,"country":"US","local_name":"Juneteenth National Independence Day"},{"date":"2026-07-03","name":"Independence Day","types":["Public","Bank"],"global":true,"country":"US","local_name":"Independence Day"},{"date":"2026-09-07","name":"Labour Day","types":["Public","Bank"],"global":true,"country":"US","local_name":"Labor Day"},{"date":"2026-10-12","name":"Columbus Day","types":["Public"],"global":false,"country":"US","counties":["US-AL","US-AZ","US-CO","US-CT","US-GA","US-ID","US-IL","US-IN","US-IA","US-KS","US-KY","US-LA","US-ME","US-MD","US-MA","US-MS","US-MO","US-MT","US-NE","US-NH","US-NJ","US-NM","US-NY","US-NC","US-OH","US-OK","US-PA","US-RI","US-SC","US-TN","US-UT","US-VA","US-WV"],"local_name":"Columbus Day"},{"date":"2026-10-12","name":"Indigenous Peoples' Day","types":["Public"],"global":false,"country":"US","counties":["US-AK","US-AL","US-CA","US-HI","US-IA","US-LA","US-ME","US-MI","US-MN","US-NC","US-NE","US-NM","US-OK","US-OR","US-SD","US-TX","US-VA","US-VT","US-WI"],"local_name":"Indigenous Peoples' Day"},{"date":"2026-11-11","name":"Veterans Day","types":["Public","Bank"],"global":true,"country":"US","local_name":"Veterans Day"},{"date":"2026-11-26","name":"Thanksgiving Day","types":["Public","Bank"],"global":true,"country":"US","local_name":"Thanksgiving Day"},{"date":"2026-12-25","name":"Christmas Day","types":["Public","Bank"],"global":true,"country":"US","local_name":"Christmas Day"},{"date":"2027-01-01","name":"New Year's Day","types":["Public","Bank"],"global":true,"country":"US","local_name":"New Year's Day"},{"date":"2027-01-18","name":"Martin Luther King, Jr. Day","types":["Public","Bank"],"global":true,"country":"US","local_name":"Martin Luther King, Jr. Day"},{"date":"2027-02-15","name":"Presidents Day","types":["Public","Bank"],"global":true,"country":"US","local_name":"Washington's Birthday"},{"date":"2027-03-26","name":"Good Friday","types":["Public"],"global":false,"country":"US","counties":["US-CT","US-DE","US-HI","US-IN","US-KY","US-LA","US-NC","US-ND","US-NJ","US-TN"],"local_name":"Good Friday"}]},"meta":{"timestamp":"2026-05-30T02:37:25.160Z","request_id":"892ceb11-2295-4e04-b8ff-7f9b1429a18f"},"status":"ok","message":"Upcoming holidays retrieved successfully","success":true}}}},"401":{"description":"Missing or invalid x-oanor-key header"},"402":{"description":"Active subscription required"},"429":{"description":"Rate-limit or monthly quota reached"},"502":{"description":"Upstream did not respond"}}}}},"x-oanor-pricing":[{"slug":"free","name":"Free","price_cents_month":0,"monthly_call_quota":5000,"rps_limit":5,"hard_limit":true},{"slug":"basic","name":"Basic","price_cents_month":900,"monthly_call_quota":50000,"rps_limit":15,"hard_limit":true},{"slug":"pro","name":"Pro","price_cents_month":2900,"monthly_call_quota":250000,"rps_limit":30,"hard_limit":true},{"slug":"mega","name":"Mega","price_cents_month":6900,"monthly_call_quota":1000000,"rps_limit":50,"hard_limit":true}],"x-oanor-marketplace-url":"https://www.oanor.com/api/holidays-api"}