{"openapi":"3.1.0","info":{"title":"Date Math","version":"1.2.0","description":"Deterministic date and time math for AI agents: date differences, business days, date arithmetic, time zone conversion and calendar facts. Paid per call via x402 (USDC on Base, $0.001); probes and spec are free. All inputs are JSON bodies; all responses are JSON objects. Errors return {\"error\":{\"code\",\"message\"}}.","x-guidance":"Date Math does exact date and time arithmetic so you don't have to. Every tool is POST with a JSON body, returns a JSON object, and costs $0.001 (x402, USDC on Base). POST /v1/diff: days/weeks/months/business days between two dates (pass country, e.g. \"US\", to skip its public holidays). POST /v1/add: the date N days/weeks/months/business days before or after a date. POST /v1/convert: a time in another IANA time zone (DST-aware). POST /v1/info: weekday, ISO week, quarter or leap-year status of a date. POST /v1/holidays: a country's public holidays for a year. POST /v1/overlap: when working hours overlap across time zones (meeting slots). POST /v1/cron: explain a cron expression and list its next runs. POST /v1/parse: turn text like \"next Friday at 3pm\" into an exact datetime. POST /v1/city: the time zone and local time of a city by name. POST /v1/recurrence: concrete dates for an iCal RRULE (\"every 2nd Tuesday\"). POST /v1/business_hours: SLA deadline N working hours from now, or working hours elapsed. Dates are YYYY-MM-DD; datetimes are ISO 8601 with Z or an offset; time zones are IANA names. Errors return HTTP 400 with {\"error\":{\"code\",\"message\"}}. Also available as an MCP server at /mcp.","contact":{"email":"jowendelapena2003@gmail.com"}},"paths":{"/v1/version":{"get":{"summary":"Service identity","responses":{"200":{"description":"Identity","content":{"application/json":{"example":{"service":"date-math","version":"1.0.0"},"schema":{"type":"object","properties":{"service":{"type":"string"},"version":{"type":"string"}},"required":["service","version"]}}}}}}},"/v1/health":{"get":{"summary":"Readiness","responses":{"200":{"description":"Ready","content":{"application/json":{"example":{"status":"ok"},"schema":{"type":"object","properties":{"status":{"type":"string","enum":["ok"]}},"required":["status"]}}}}}}},"/v1/info":{"post":{"summary":"Calendar facts for a date (weekday, ISO week, quarter, day of year, leap year)","requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/InfoRequest"}}}},"responses":{"200":{"description":"Successful response","content":{"application/json":{"schema":{"type":"object","properties":{"date":{"type":"string"},"weekday":{"type":"string"},"weekday_number":{"type":"integer","description":"ISO: Monday=1 … Sunday=7"},"iso_year":{"type":"integer"},"iso_week":{"type":"integer"},"quarter":{"type":"integer"},"day_of_year":{"type":"integer"},"days_in_year":{"type":"integer"},"days_remaining_in_year":{"type":"integer"},"days_in_month":{"type":"integer"},"is_leap_year":{"type":"boolean"},"is_weekend":{"type":"boolean"},"unix_seconds":{"type":"integer"}},"required":["date","weekday","iso_week","quarter","day_of_year","is_leap_year","is_weekend"]},"example":{"date":"2026-11-07","weekday":"Saturday","weekday_number":6,"iso_year":2026,"iso_week":45,"quarter":4,"day_of_year":311,"days_in_year":365,"days_remaining_in_year":54,"days_in_month":30,"is_leap_year":false,"is_weekend":true,"unix_seconds":1794009600}}}},"400":{"$ref":"#/components/responses/Error"},"402":{"description":"Payment Required"}},"operationId":"info","x-payment-info":{"price":{"mode":"fixed","currency":"USD","amount":"0.001"},"protocols":[{"x402":{}}]},"tags":["Calendar"]}},"/v1/diff":{"post":{"summary":"Difference between two dates or datetimes, including business days","requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/DiffRequest"}}}},"responses":{"200":{"description":"Successful response","content":{"application/json":{"schema":{"type":"object","properties":{"from":{"type":"string"},"to":{"type":"string"},"direction":{"type":"string","enum":["forward","backward"]},"total_days":{"type":"integer"},"total_weeks":{"type":"integer"},"calendar":{"$ref":"#/components/schemas/CalendarParts"},"business_days":{"type":"integer","description":"Weekdays in [from, to) minus holidays (date inputs only)"},"total_hours":{"type":"integer","description":"Datetime inputs only"},"total_minutes":{"type":"integer"},"total_seconds":{"type":"integer"},"iso_duration":{"type":"string","example":"P1M15D"}},"required":["from","to","direction","total_days","total_weeks","calendar","iso_duration"]},"example":{"from":"2026-01-31","to":"2026-03-15","direction":"forward","total_days":43,"total_weeks":6,"calendar":{"years":0,"months":1,"days":15},"business_days":30,"iso_duration":"P1M15D"}}}},"400":{"$ref":"#/components/responses/Error"},"402":{"description":"Payment Required"}},"operationId":"diff","x-payment-info":{"price":{"mode":"fixed","currency":"USD","amount":"0.001"},"protocols":[{"x402":{}}]},"tags":["Date arithmetic"]}},"/v1/add":{"post":{"summary":"Add or subtract a duration (calendar units, business days, time units)","requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/AddRequest"}}}},"responses":{"200":{"description":"Successful response","content":{"application/json":{"schema":{"type":"object","properties":{"input":{"type":"string"},"result":{"type":"string","description":"YYYY-MM-DD, or ISO datetime (UTC) for datetime input"},"weekday":{"type":"string"},"is_business_day":{"type":"boolean"}},"required":["input","result","weekday","is_business_day"]},"example":{"input":"2026-11-06","result":"2026-11-20","weekday":"Friday","is_business_day":true}}}},"400":{"$ref":"#/components/responses/Error"},"402":{"description":"Payment Required"}},"operationId":"add","x-payment-info":{"price":{"mode":"fixed","currency":"USD","amount":"0.001"},"protocols":[{"x402":{}}]},"tags":["Date arithmetic"]}},"/v1/convert":{"post":{"summary":"Convert an instant or local wall-clock time between IANA time zones","requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ConvertRequest"}}}},"responses":{"200":{"description":"Successful response","content":{"application/json":{"schema":{"type":"object","properties":{"utc":{"type":"string"},"unix_seconds":{"type":"integer"},"from":{"$ref":"#/components/schemas/ZonedView"},"to":{"$ref":"#/components/schemas/ZonedView"}},"required":["utc","unix_seconds","from","to"]},"example":{"utc":"2026-11-07T06:30:00Z","unix_seconds":1794033000,"from":{"timezone":"Asia/Manila","datetime":"2026-11-07T14:30:00+08:00","date":"2026-11-07","time":"14:30:00","weekday":"Saturday","utc_offset":"+08:00"},"to":{"timezone":"America/New_York","datetime":"2026-11-07T01:30:00-05:00","date":"2026-11-07","time":"01:30:00","weekday":"Saturday","utc_offset":"-05:00"}}}}},"400":{"$ref":"#/components/responses/Error"},"402":{"description":"Payment Required"}},"operationId":"convert","x-payment-info":{"price":{"mode":"fixed","currency":"USD","amount":"0.001"},"protocols":[{"x402":{}}]},"tags":["Time zones"]}},"/v1/holidays":{"post":{"operationId":"holidays","summary":"Public holidays for a country and year (207 countries, 2000–2050)","tags":["Calendar"],"x-payment-info":{"price":{"mode":"fixed","currency":"USD","amount":"0.001"},"protocols":[{"x402":{}}]},"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["country"],"properties":{"country":{"$ref":"#/components/schemas/Country"},"year":{"type":"integer","minimum":2000,"maximum":2050,"description":"Defaults to the current year"}}},"example":{"country":"PH","year":2026}}}},"responses":{"200":{"description":"Successful response","content":{"application/json":{"schema":{"type":"object","required":["country","year","count","holidays"],"properties":{"country":{"type":"string"},"country_name":{"type":"string"},"year":{"type":"integer"},"type":{"type":"string","enum":["public"]},"count":{"type":"integer"},"holidays":{"type":"array","items":{"type":"object","required":["date","name"],"properties":{"date":{"type":"string"},"name":{"type":"string"},"substitute":{"type":"boolean","description":"Observed on another day because the holiday falls on a weekend"}}}},"source":{"type":"string","description":"Data attribution"}}}}}},"400":{"description":"Invalid input","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"402":{"description":"Payment Required"}}}},"/v1/overlap":{"post":{"operationId":"overlap","summary":"Working-hours overlap across time zones (meeting windows)","tags":["Time zones"],"x-payment-info":{"price":{"mode":"fixed","currency":"USD","amount":"0.001"},"protocols":[{"x402":{}}]},"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","description":"Pass \"timezones\" (strings) or \"participants\" (objects with their own hours).","properties":{"timezones":{"type":"array","minItems":2,"maxItems":10,"items":{"type":"string","description":"IANA time zone, e.g. Asia/Manila"}},"participants":{"type":"array","minItems":2,"maxItems":10,"items":{"type":"object","required":["timezone"],"properties":{"timezone":{"type":"string","description":"IANA time zone, e.g. Asia/Manila"},"work_start":{"type":"string","pattern":"^([01]\\d|2[0-4]):[0-5]\\d$","example":"09:00"},"work_end":{"type":"string","pattern":"^([01]\\d|2[0-4]):[0-5]\\d$","example":"09:00"}}}},"date":{"type":"string","description":"YYYY-MM-DD in the first participant's zone; defaults to today"},"days":{"type":"integer","minimum":1,"maximum":14,"description":"Number of days to search (default 1)"},"work_start":{"type":"string","pattern":"^([01]\\d|2[0-4]):[0-5]\\d$","example":"09:00"},"work_end":{"type":"string","pattern":"^([01]\\d|2[0-4]):[0-5]\\d$","example":"17:00"},"skip_weekends":{"type":"boolean","description":"Default true"}}},"example":{"timezones":["Asia/Manila","Europe/London"],"date":"2026-11-10","work_start":"09:00","work_end":"18:00"}}}},"responses":{"200":{"description":"Successful response","content":{"application/json":{"schema":{"type":"object","required":["reference_timezone","total_overlap_minutes","windows"],"properties":{"reference_timezone":{"type":"string"},"from":{"type":"string"},"to":{"type":"string"},"participants":{"type":"array","items":{"type":"object"}},"total_overlap_minutes":{"type":"number"},"windows":{"type":"array","items":{"type":"object","properties":{"start_utc":{"type":"string"},"end_utc":{"type":"string"},"duration_minutes":{"type":"number"},"local":{"type":"array","items":{"type":"object","properties":{"timezone":{"type":"string"},"start":{"type":"string"},"end":{"type":"string"}}}}}}}}}}}},"400":{"description":"Invalid input","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"402":{"description":"Payment Required"}}}},"/v1/cron":{"post":{"operationId":"cron","summary":"Explain a cron expression and list its next run times","tags":["Scheduling"],"x-payment-info":{"price":{"mode":"fixed","currency":"USD","amount":"0.001"},"protocols":[{"x402":{}}]},"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["expression"],"properties":{"expression":{"type":"string","description":"5- or 6-field cron expression","example":"0 9 * * 1-5"},"timezone":{"type":"string","description":"Default UTC"},"count":{"type":"integer","minimum":1,"maximum":100,"description":"Default 5"},"from":{"type":"string","description":"ISO 8601 datetime with offset; default now"}}},"example":{"expression":"0 9 * * 1-5","timezone":"Asia/Manila","count":3}}}},"responses":{"200":{"description":"Successful response","content":{"application/json":{"schema":{"type":"object","required":["expression","timezone","description","next_runs"],"properties":{"expression":{"type":"string"},"timezone":{"type":"string"},"description":{"type":"string"},"from":{"type":"string"},"next_runs":{"type":"array","items":{"type":"object","properties":{"utc":{"type":"string"},"local":{"type":"string"},"weekday":{"type":"string"}}}}}}}}},"400":{"description":"Invalid input","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"402":{"description":"Payment Required"}}}},"/v1/parse":{"post":{"operationId":"parse","summary":"Resolve natural-language dates to exact datetimes","tags":["Parsing"],"x-payment-info":{"price":{"mode":"fixed","currency":"USD","amount":"0.001"},"protocols":[{"x402":{}}]},"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["text"],"properties":{"text":{"type":"string","maxLength":1000,"example":"next friday at 3pm"},"timezone":{"type":"string","description":"Default UTC"},"reference":{"type":"string","description":"ISO 8601 datetime the text is relative to; default now"},"forward_date":{"type":"boolean","description":"Prefer future dates for ambiguous text (default true)"}}},"example":{"text":"next friday at 3pm","timezone":"Asia/Manila","reference":"2026-11-07T14:00:00+08:00"}}}},"responses":{"200":{"description":"Successful response","content":{"application/json":{"schema":{"type":"object","required":["text","timezone","count","results"],"properties":{"text":{"type":"string"},"timezone":{"type":"string"},"reference":{"type":"string"},"count":{"type":"integer"},"results":{"type":"array","items":{"type":"object","properties":{"matched":{"type":"string"},"index":{"type":"integer"},"start":{"type":"object","properties":{"utc":{"type":"string"},"local":{"type":"string"},"date":{"type":"string"},"weekday":{"type":"string"}},"required":["utc","local"]},"end":{"type":"object","properties":{"utc":{"type":"string"},"local":{"type":"string"},"date":{"type":"string"},"weekday":{"type":"string"}},"required":["utc","local"]},"certain":{"type":"array","items":{"type":"string"}}}}}}}}}},"400":{"description":"Invalid input","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"402":{"description":"Payment Required"}}}},"/v1/city":{"post":{"operationId":"city","summary":"Time zone and local time for cities by name","tags":["Time zones"],"x-payment-info":{"price":{"mode":"fixed","currency":"USD","amount":"0.001"},"protocols":[{"x402":{}}]},"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","description":"Pass \"city\" or \"cities\".","properties":{"city":{"type":"string","example":"Cebu"},"cities":{"type":"array","minItems":1,"maxItems":10,"items":{"type":"string"}},"country":{"$ref":"#/components/schemas/Country"},"at":{"type":"string","description":"ISO 8601 instant to show local time for; default now"}}},"example":{"cities":["Cebu","London","New York"]}}}},"responses":{"200":{"description":"Successful response","content":{"application/json":{"schema":{"type":"object","required":["at","results"],"properties":{"at":{"type":"string"},"results":{"type":"array","items":{"type":"object","properties":{"query":{"type":"string"},"found":{"type":"boolean"},"best":{"type":["object","null"],"properties":{"name":{"type":"string"},"country":{"type":"string"},"region":{"type":"string"},"timezone":{"type":"string"},"population":{"type":"integer"},"match":{"type":"string"},"local_time":{"type":"string"},"weekday":{"type":"string"},"utc_offset":{"type":"string"}}},"alternatives":{"type":"array","items":{"type":"object"}}}}}}}}}},"400":{"description":"Invalid input","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"402":{"description":"Payment Required"}}}},"/v1/recurrence":{"post":{"operationId":"recurrence","summary":"Expand an iCalendar RRULE into concrete dates (DST-aware)","tags":["Scheduling"],"x-payment-info":{"price":{"mode":"fixed","currency":"USD","amount":"0.001"},"protocols":[{"x402":{}}]},"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["rrule","start"],"properties":{"rrule":{"type":"string","example":"FREQ=MONTHLY;BYDAY=2TU","description":"iCalendar RRULE (no DTSTART/TZID inside)"},"start":{"type":"string","description":"Local start date or datetime in timezone, e.g. 2026-01-01T10:00"},"timezone":{"type":"string","description":"Default UTC"},"count":{"type":"integer","minimum":1,"maximum":200,"description":"Default 10"},"exclude":{"type":"array","items":{"type":"string"},"description":"Local dates (YYYY-MM-DD) to skip"}}},"example":{"rrule":"FREQ=MONTHLY;BYDAY=2TU","start":"2026-01-01T10:00","timezone":"Asia/Manila","count":3}}}},"responses":{"200":{"description":"Successful response","content":{"application/json":{"schema":{"type":"object","required":["rrule","timezone","count","occurrences"],"properties":{"rrule":{"type":"string"},"timezone":{"type":"string"},"start":{"type":"string"},"description":{"type":"string"},"count":{"type":"integer"},"occurrences":{"type":"array","items":{"type":"object","properties":{"local":{"type":"string"},"date":{"type":"string"},"weekday":{"type":"string"},"utc":{"type":"string"}}}}}}}}},"400":{"description":"Invalid input","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"402":{"description":"Payment Required"}}}},"/v1/business_hours":{"post":{"operationId":"businessHours","summary":"Business-hours deadline (SLA) or business time elapsed","tags":["Date arithmetic"],"x-payment-info":{"price":{"mode":"fixed","currency":"USD","amount":"0.001"},"protocols":[{"x402":{}}]},"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["timezone"],"description":"Pass \"hours\"/\"minutes\" to get a deadline, or \"end\" to count business time between start and end.","properties":{"timezone":{"type":"string","description":"IANA time zone, e.g. Asia/Manila"},"start":{"type":"string","description":"Local datetime in timezone or ISO 8601 with offset; default now"},"hours":{"type":"number","minimum":0,"maximum":2000},"minutes":{"type":"number","minimum":0},"end":{"type":"string","description":"Count business time from start to end (max 1 year)"},"work_start":{"type":"string","pattern":"^([01]\\d|2[0-4]):[0-5]\\d$","example":"09:00"},"work_end":{"type":"string","pattern":"^([01]\\d|2[0-4]):[0-5]\\d$","example":"17:00"},"workdays":{"type":"array","items":{"type":"integer","minimum":0,"maximum":6},"description":"0 = Sunday; default [1,2,3,4,5]"},"country":{"$ref":"#/components/schemas/Country"},"holidays":{"type":"array","items":{"type":"string"}}}},"example":{"start":"2026-11-06T16:00","hours":2,"timezone":"Asia/Manila","work_start":"09:00","work_end":"17:00","country":"PH"}}}},"responses":{"200":{"description":"Successful response","content":{"application/json":{"schema":{"type":"object","required":["mode","timezone","start","business_minutes"],"properties":{"mode":{"type":"string","enum":["deadline","elapsed"]},"timezone":{"type":"string"},"start":{"type":"string"},"end":{"type":"string"},"business_minutes":{"type":"number"},"business_hours":{"type":"number"},"deadline":{"type":"string"},"deadline_utc":{"type":"string"},"weekday":{"type":"string"}}}}}},"400":{"description":"Invalid input","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"402":{"description":"Payment Required"}}}}},"components":{"schemas":{"Date":{"type":"string","pattern":"^\\d{4}-\\d{2}-\\d{2}$","example":"2026-11-07"},"DateOrDateTime":{"type":"string","description":"YYYY-MM-DD, or ISO 8601 datetime with Z or offset","example":"2026-11-07T14:30:00Z"},"Holidays":{"type":"array","maxItems":1000,"items":{"$ref":"#/components/schemas/Date"},"description":"Dates excluded from business-day counts (weekends are always excluded)"},"InfoRequest":{"type":"object","required":["date"],"properties":{"date":{"$ref":"#/components/schemas/Date"}}},"DiffRequest":{"type":"object","required":["from","to"],"properties":{"from":{"$ref":"#/components/schemas/DateOrDateTime"},"to":{"$ref":"#/components/schemas/DateOrDateTime"},"holidays":{"$ref":"#/components/schemas/Holidays"},"country":{"$ref":"#/components/schemas/Country"}},"description":"business_days counts weekdays in [from, to) minus holidays; only for date inputs."},"AddRequest":{"type":"object","required":["date"],"properties":{"date":{"$ref":"#/components/schemas/DateOrDateTime"},"years":{"type":"integer"},"months":{"type":"integer"},"weeks":{"type":"integer"},"days":{"type":"integer"},"business_days":{"type":"integer","description":"Applied after calendar units; skips weekends and holidays"},"hours":{"type":"integer"},"minutes":{"type":"integer"},"seconds":{"type":"integer"},"holidays":{"$ref":"#/components/schemas/Holidays"},"country":{"$ref":"#/components/schemas/Country"}},"description":"Negative values subtract. Months clamp to month end (Jan 31 + 1 month = Feb 28/29). Time units require a datetime input."},"ConvertRequest":{"type":"object","required":["to_timezone"],"properties":{"datetime":{"type":"string","description":"ISO 8601 with offset, local YYYY-MM-DDTHH:MM[:SS] (needs from_timezone), or \"now\" (default)"},"from_timezone":{"type":"string","example":"Asia/Manila"},"to_timezone":{"type":"string","example":"America/New_York"}}},"Error":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"}}}}},"CalendarParts":{"type":"object","properties":{"years":{"type":"integer"},"months":{"type":"integer"},"days":{"type":"integer"}},"required":["years","months","days"]},"ZonedView":{"type":"object","properties":{"timezone":{"type":"string"},"datetime":{"type":"string","description":"ISO 8601 with offset"},"date":{"type":"string"},"time":{"type":"string"},"weekday":{"type":"string"},"utc_offset":{"type":"string"}},"required":["timezone","datetime","date","time","weekday","utc_offset"]},"Country":{"type":"string","pattern":"^[A-Za-z]{2}$","description":"ISO 3166-1 alpha-2 country code (207 countries); its public holidays (2000–2050) are excluded from business days","example":"US"}},"responses":{"Error":{"description":"Invalid input","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}},"servers":[{"url":"https://date-math.datemath.workers.dev"}]}