{ "openapi": "3.0.3", "info": { "title": "HolidayExplore Global Banking & Chronometry REST API", "version": "1.0.0", "description": "Free, zero-auth public REST API for statutory public holidays, central bank RTGS wholesale settlement cutoffs, retail clearing rails, working day calculations, and real-time operational banking status across 48 sovereign economies. Maintained by HolidayExplore (https://holidayexplore.com) under official central bank circulars and statutory labor codes.", "contact": { "name": "HolidayExplore Chronometry Desk", "url": "https://holidayexplore.com/about/", "email": "contact@holidayexplore.com" }, "license": { "name": "Open Data Commons / CC BY 4.0", "url": "https://holidayexplore.com/terms/" } }, "servers": [ { "url": "https://holidayexplore.com", "description": "Production Edge Network (Cloudflare Global Anycast / V8 Edge Workers)" } ], "paths": { "/api/v1/holidays": { "get": { "summary": "Filter statutory & bank holidays by country, year, type, and month", "description": "Returns statutory public and commercial bank holidays for any of the 48 sovereign countries, with optional filtering by calendar year (2026, 2027), holiday type, or specific month.", "operationId": "getHolidaysRest", "parameters": [ { "name": "country", "in": "query", "required": true, "description": "ISO 3166-1 alpha-2 country code (e.g. US, GB, DE, IN, JP, AU, CA)", "schema": { "type": "string", "example": "US" } }, { "name": "year", "in": "query", "required": false, "description": "Calendar year (2026 or 2027)", "schema": { "type": "string", "enum": [ "2026", "2027" ], "example": "2026" } }, { "name": "month", "in": "query", "required": false, "description": "Month number (1-12)", "schema": { "type": "integer", "minimum": 1, "maximum": 12, "example": 12 } }, { "name": "type", "in": "query", "required": false, "description": "Holiday classification filter (bank, statutory, public, all)", "schema": { "type": "string", "default": "all", "example": "bank" } } ], "responses": { "200": { "description": "Filtered holiday calendar with day of week and weekend collision status.", "content": { "application/json": { "schema": { "type": "object", "properties": { "country_code": { "type": "string", "example": "US" }, "country_name": { "type": "string", "example": "United States" }, "region": { "type": "string", "example": "Americas" }, "total_holidays": { "type": "integer", "example": 12 }, "filter": { "type": "object" }, "holidays": { "type": "array", "items": { "type": "object", "properties": { "date": { "type": "string", "format": "date", "example": "2026-01-01" }, "name": { "type": "string", "example": "New Year's Day" }, "day_of_week": { "type": "string", "example": "Thursday" }, "is_weekend": { "type": "boolean", "example": false }, "type": { "type": "string", "example": "Public / Statutory Holiday" } } } }, "attribution": { "type": "object" } } } } } }, "400": { "description": "Missing or invalid query parameters." }, "404": { "description": "Country code not recognized." } } } }, "/api/v1/status": { "get": { "summary": "Live banking, central bank RTGS, and market status", "description": "Evaluates whether bank branches, equity markets, and wholesale central bank RTGS settlement rails are active, paused, or closed for any sovereign country code and target date (defaults to country local today).", "operationId": "getStatusRest", "parameters": [ { "name": "country", "in": "query", "required": true, "description": "ISO 3166-1 alpha-2 country code (e.g. GB, US, IN, AU, DE, SG)", "schema": { "type": "string", "example": "GB" } }, { "name": "date", "in": "query", "required": false, "description": "Target evaluation date in YYYY-MM-DD format (defaults to current local date in country capital timezone)", "schema": { "type": "string", "format": "date", "example": "2026-12-25" } } ], "responses": { "200": { "description": "Live operational status across banking, RTGS, ACH, and 24/7 instant rails.", "content": { "application/json": { "schema": { "type": "object", "properties": { "country_code": { "type": "string", "example": "GB" }, "country_name": { "type": "string", "example": "United Kingdom" }, "date": { "type": "string", "format": "date", "example": "2026-12-25" }, "day_of_week": { "type": "string", "example": "Friday" }, "timezone": { "type": "string", "example": "Europe/London" }, "is_weekend": { "type": "boolean", "example": false }, "is_public_holiday": { "type": "boolean", "example": true }, "holiday_name": { "type": "string", "example": "Christmas Day" }, "is_bank_open": { "type": "boolean", "example": false }, "is_market_open": { "type": "boolean", "example": false }, "rtgs_rail": { "type": "object" }, "ach_rail": { "type": "object" }, "instant_rail": { "type": "object" }, "next_holiday": { "type": "object" } } } } } }, "400": { "description": "Invalid date format or country code." } } } }, "/api/v1/working-days": { "get": { "summary": "Calculate net business days, weekends, and billable hours", "description": "Accurately calculates net working business days, weekend rest days, statutory public holidays, and total billable work hours between two dates for payroll, SLA, and contract management.", "operationId": "getWorkingDaysRest", "parameters": [ { "name": "country", "in": "query", "required": true, "description": "ISO 3166-1 alpha-2 country code (e.g. US, GB, CA, IN, AU)", "schema": { "type": "string", "example": "US" } }, { "name": "start", "in": "query", "required": true, "description": "Start date (YYYY-MM-DD)", "schema": { "type": "string", "format": "date", "example": "2026-11-01" } }, { "name": "end", "in": "query", "required": true, "description": "End date (YYYY-MM-DD)", "schema": { "type": "string", "format": "date", "example": "2026-11-30" } }, { "name": "hours_per_day", "in": "query", "required": false, "description": "Standard working hours per day (default 8.0)", "schema": { "type": "number", "default": 8, "example": 8 } } ], "responses": { "200": { "description": "Detailed breakdown of working days, weekend exclusions, and billable hours.", "content": { "application/json": { "schema": { "type": "object", "properties": { "country_code": { "type": "string", "example": "US" }, "country_name": { "type": "string", "example": "United States" }, "start_date": { "type": "string", "example": "2026-11-01" }, "end_date": { "type": "string", "example": "2026-11-30" }, "calendar_days": { "type": "integer", "example": 30 }, "weekend_days": { "type": "integer", "example": 9 }, "public_holidays_on_weekdays": { "type": "integer", "example": 2 }, "total_holidays_in_period": { "type": "integer", "example": 2 }, "net_working_days": { "type": "integer", "example": 19 }, "standard_hours_per_day": { "type": "number", "example": 8 }, "total_billable_hours": { "type": "number", "example": 152 }, "holidays_in_period": { "type": "array" } } } } } }, "400": { "description": "Missing or invalid parameters." } } } }, "/api/v1/countries": { "get": { "summary": "Directory of supported countries and central bank payment rails", "description": "Returns the list of 48 sovereign countries with optional filtering by geographic region (Europe, Americas, Asia-Pacific, Africa, Middle East) or payment rail (SEPA, Fedwire, BACS, ACH, RTP, PIX).", "operationId": "getCountriesRest", "parameters": [ { "name": "region", "in": "query", "required": false, "description": "Geographic region filter (e.g. Europe, Americas, Asia-Pacific)", "schema": { "type": "string", "example": "Europe" } }, { "name": "rail", "in": "query", "required": false, "description": "Payment rail filter (e.g. SEPA, ACH, Fedwire, BACS, RTP)", "schema": { "type": "string", "example": "SEPA" } }, { "name": "search", "in": "query", "required": false, "description": "Search keyword matching country name or ISO code", "schema": { "type": "string", "example": "United" } } ], "responses": { "200": { "description": "Array of matching sovereign countries and payment rail specifications.", "content": { "application/json": { "schema": { "type": "object", "properties": { "total": { "type": "integer", "example": 9 }, "filter": { "type": "object" }, "countries": { "type": "array", "items": { "type": "object", "properties": { "code": { "type": "string", "example": "DE" }, "name": { "type": "string", "example": "Germany" }, "region": { "type": "string", "example": "Europe" }, "timezone": { "type": "string", "example": "Europe/Berlin" }, "hub_url": { "type": "string", "example": "https://holidayexplore.com/de/" }, "rtgs_rail": { "type": "string", "example": "Eurosystem TARGET2 / T2" }, "ach_rail": { "type": "string", "example": "SEPA Credit Transfer & Direct Debit" }, "instant_rail": { "type": "string", "example": "SEPA Instant Credit Transfer" } } } } } } } } } } } }, "/api/v1/countries.json": { "get": { "summary": "Static Directory: List all 48 supported sovereign economies", "description": "Static JSON file returning all 48 sovereign nations with ISO codes, primary timezones, currencies, domestic wholesale RTGS rails, and batch clearing systems.", "operationId": "getCountriesJson", "responses": { "200": { "description": "Successful response containing array of sovereign jurisdictions." } } } }, "/api/v1/holidays/{code}.json": { "get": { "summary": "Static Calendar: 2026–2027 statutory & bank holiday calendar", "description": "Static JSON calendar file returning all verified public and commercial bank holidays for a country.", "operationId": "getHolidaysByCountryJson", "parameters": [ { "name": "code", "in": "path", "required": true, "description": "ISO 3166-1 alpha-2 country code (e.g. us, gb, de, in, jp, au, ca)", "schema": { "type": "string", "example": "us" } } ], "responses": { "200": { "description": "Calendar payload." } } } }, "/api/v1/status/{code}/today.json": { "get": { "summary": "Static Status: Operational status today", "description": "Static JSON endpoint for today's operational bank status.", "operationId": "getTodayStatusByCountryJson", "parameters": [ { "name": "code", "in": "path", "required": true, "description": "ISO 3166-1 alpha-2 country code", "schema": { "type": "string", "example": "us" } } ], "responses": { "200": { "description": "Status payload." } } } } } }