{"openapi":"3.0.3","info":{"title":"Business Days & Holidays API","version":"1.0.0","description":"Public holidays and business-day arithmetic for 240+ countries and their\nstates, provinces and cantons.\n\nMost holiday APIs hand you a list of dates and leave the hard part to you.\nThis one answers the questions you actually have: *when does this ship*,\n*is that within SLA*, *is the Frankfurt office open right now*.\n\nIt also models weekends correctly per country — Israel, Saudi Arabia and\nEgypt run Friday–Saturday, and assuming Saturday–Sunday silently corrupts\nevery result for those markets.","contact":{"name":"API support"},"license":{"name":"Commercial"}},"servers":[{"url":"https://businessdays.maodjinn.com"}],"paths":{"/v1/countries":{"get":{"summary":"List supported countries","description":"Every supported country with its ISO codes, primary timezones, weekend definition and available subdivisions.","parameters":[],"responses":{"200":{"description":"The supported calendar catalogue.","content":{"application/json":{"schema":{"type":"object"}}}},"400":{"description":"Invalid parameters.","content":{"application/json":{"schema":{"type":"object"}}}},"401":{"description":"Missing or invalid API key.","content":{"application/json":{"schema":{"type":"object"}}}},"404":{"description":"Unknown country or subdivision.","content":{"application/json":{"schema":{"type":"object"}}}}}}},"/v1/holidays":{"get":{"summary":"List holidays","description":"Holidays for a calendar year, or for an explicit `from`/`to` range.","parameters":[{"name":"country","in":"query","required":true,"description":"ISO 3166-1 alpha-2 (or alpha-3) country code.","example":"US","schema":{"type":"string"}},{"name":"subdivision","in":"query","required":false,"description":"Optional state/province/canton code, adding that region’s holidays on top of the national calendar.","example":"CA","schema":{"type":"string"}},{"name":"year","in":"query","required":false,"description":"Calendar year (2024–2032). Defaults to the current year.","example":"2026","schema":{"type":"integer","minimum":2024,"maximum":2032}},{"name":"from","in":"query","required":false,"description":"Start of an explicit range (YYYY-MM-DD). Overrides `year`.","example":"","schema":{"type":"string"}},{"name":"to","in":"query","required":false,"description":"End of an explicit range (YYYY-MM-DD).","example":"","schema":{"type":"string"}}],"responses":{"200":{"description":"Holidays in the requested window.","content":{"application/json":{"schema":{"type":"object"}}}},"400":{"description":"Invalid parameters.","content":{"application/json":{"schema":{"type":"object"}}}},"401":{"description":"Missing or invalid API key.","content":{"application/json":{"schema":{"type":"object"}}}},"404":{"description":"Unknown country or subdivision.","content":{"application/json":{"schema":{"type":"object"}}}}}}},"/v1/date":{"get":{"summary":"Classify a single date","description":"Whether a date is a business day, a weekend or a holiday — and which holiday.","parameters":[{"name":"date","in":"query","required":true,"description":"The date to classify (YYYY-MM-DD).","example":"2026-07-04","schema":{"type":"string"}},{"name":"country","in":"query","required":true,"description":"ISO 3166-1 alpha-2 (or alpha-3) country code.","example":"US","schema":{"type":"string"}},{"name":"subdivision","in":"query","required":false,"description":"Optional state/province/canton code, adding that region’s holidays on top of the national calendar.","example":"CA","schema":{"type":"string"}}],"responses":{"200":{"description":"The classification of that date.","content":{"application/json":{"schema":{"type":"object"}}}},"400":{"description":"Invalid parameters.","content":{"application/json":{"schema":{"type":"object"}}}},"401":{"description":"Missing or invalid API key.","content":{"application/json":{"schema":{"type":"object"}}}},"404":{"description":"Unknown country or subdivision.","content":{"application/json":{"schema":{"type":"object"}}}}}}},"/v1/add":{"get":{"summary":"Add or subtract business days","description":"Shifts a date by N business days, skipping weekends and holidays. Use a negative `days` to go backwards. Ideal for delivery estimates, SLA deadlines and settlement dates.","parameters":[{"name":"date","in":"query","required":true,"description":"Starting date (YYYY-MM-DD).","example":"2026-12-23","schema":{"type":"string"}},{"name":"days","in":"query","required":true,"description":"Business days to add; negative subtracts.","example":"5","schema":{"type":"integer","minimum":-2000,"maximum":2000}},{"name":"country","in":"query","required":true,"description":"ISO 3166-1 alpha-2 (or alpha-3) country code.","example":"US","schema":{"type":"string"}},{"name":"subdivision","in":"query","required":false,"description":"Optional state/province/canton code, adding that region’s holidays on top of the national calendar.","example":"CA","schema":{"type":"string"}}],"responses":{"200":{"description":"The resulting date, plus how many calendar days that spanned.","content":{"application/json":{"schema":{"type":"object"}}}},"400":{"description":"Invalid parameters.","content":{"application/json":{"schema":{"type":"object"}}}},"401":{"description":"Missing or invalid API key.","content":{"application/json":{"schema":{"type":"object"}}}},"404":{"description":"Unknown country or subdivision.","content":{"application/json":{"schema":{"type":"object"}}}}}}},"/v1/diff":{"get":{"summary":"Count business days between two dates","description":"Business days in the half-open interval `(from, to]`, so the result composes with /v1/add. Negative when `to` precedes `from`.","parameters":[{"name":"from","in":"query","required":true,"description":"Start date (YYYY-MM-DD).","example":"2026-12-23","schema":{"type":"string"}},{"name":"to","in":"query","required":true,"description":"End date (YYYY-MM-DD).","example":"2027-01-06","schema":{"type":"string"}},{"name":"country","in":"query","required":true,"description":"ISO 3166-1 alpha-2 (or alpha-3) country code.","example":"US","schema":{"type":"string"}},{"name":"subdivision","in":"query","required":false,"description":"Optional state/province/canton code, adding that region’s holidays on top of the national calendar.","example":"CA","schema":{"type":"string"}}],"responses":{"200":{"description":"The business-day and calendar-day counts.","content":{"application/json":{"schema":{"type":"object"}}}},"400":{"description":"Invalid parameters.","content":{"application/json":{"schema":{"type":"object"}}}},"401":{"description":"Missing or invalid API key.","content":{"application/json":{"schema":{"type":"object"}}}},"404":{"description":"Unknown country or subdivision.","content":{"application/json":{"schema":{"type":"object"}}}}}}},"/v1/next":{"get":{"summary":"Next business day","description":"The next working day on or after a date.","parameters":[{"name":"date","in":"query","required":true,"description":"Reference date (YYYY-MM-DD).","example":"2026-12-25","schema":{"type":"string"}},{"name":"country","in":"query","required":true,"description":"ISO 3166-1 alpha-2 (or alpha-3) country code.","example":"US","schema":{"type":"string"}},{"name":"subdivision","in":"query","required":false,"description":"Optional state/province/canton code, adding that region’s holidays on top of the national calendar.","example":"CA","schema":{"type":"string"}},{"name":"inclusive","in":"query","required":false,"description":"When `false`, always moves at least one day forward. Defaults to `true`.","example":"true","schema":{"type":"boolean","default":true}}],"responses":{"200":{"description":"The next working day.","content":{"application/json":{"schema":{"type":"object"}}}},"400":{"description":"Invalid parameters.","content":{"application/json":{"schema":{"type":"object"}}}},"401":{"description":"Missing or invalid API key.","content":{"application/json":{"schema":{"type":"object"}}}},"404":{"description":"Unknown country or subdivision.","content":{"application/json":{"schema":{"type":"object"}}}}}}},"/v1/previous":{"get":{"summary":"Previous business day","description":"The most recent working day on or before a date.","parameters":[{"name":"date","in":"query","required":true,"description":"Reference date (YYYY-MM-DD).","example":"2026-12-25","schema":{"type":"string"}},{"name":"country","in":"query","required":true,"description":"ISO 3166-1 alpha-2 (or alpha-3) country code.","example":"US","schema":{"type":"string"}},{"name":"subdivision","in":"query","required":false,"description":"Optional state/province/canton code, adding that region’s holidays on top of the national calendar.","example":"CA","schema":{"type":"string"}},{"name":"inclusive","in":"query","required":false,"description":"When `false`, always moves at least one day backward. Defaults to `true`.","example":"true","schema":{"type":"boolean","default":true}}],"responses":{"200":{"description":"The previous working day.","content":{"application/json":{"schema":{"type":"object"}}}},"400":{"description":"Invalid parameters.","content":{"application/json":{"schema":{"type":"object"}}}},"401":{"description":"Missing or invalid API key.","content":{"application/json":{"schema":{"type":"object"}}}},"404":{"description":"Unknown country or subdivision.","content":{"application/json":{"schema":{"type":"object"}}}}}}},"/v1/status":{"get":{"summary":"Is it open right now?","description":"Evaluates the country’s calendar against local wall-clock time to say whether business hours are currently in effect — and when they next start. Useful for support routing, live chat availability and \"expect a reply by\" copy.","parameters":[{"name":"country","in":"query","required":true,"description":"ISO 3166-1 alpha-2 (or alpha-3) country code.","example":"US","schema":{"type":"string"}},{"name":"subdivision","in":"query","required":false,"description":"Optional state/province/canton code, adding that region’s holidays on top of the national calendar.","example":"CA","schema":{"type":"string"}},{"name":"timezone","in":"query","required":false,"description":"IANA timezone. Defaults to the country’s primary zone.","example":"Europe/Berlin","schema":{"type":"string"}},{"name":"opens","in":"query","required":false,"description":"Local opening time (HH:MM). Defaults to 09:00.","example":"09:00","schema":{"type":"string"}},{"name":"closes","in":"query","required":false,"description":"Local closing time (HH:MM). Defaults to 17:00.","example":"17:00","schema":{"type":"string"}}],"responses":{"200":{"description":"Current open/closed state and the next opening.","content":{"application/json":{"schema":{"type":"object"}}}},"400":{"description":"Invalid parameters.","content":{"application/json":{"schema":{"type":"object"}}}},"401":{"description":"Missing or invalid API key.","content":{"application/json":{"schema":{"type":"object"}}}},"404":{"description":"Unknown country or subdivision.","content":{"application/json":{"schema":{"type":"object"}}}}}}}},"components":{"securitySchemes":{"ApiKey":{"type":"apiKey","in":"header","name":"X-API-Key"}}},"security":[{"ApiKey":[]}]}