time_date_difference
Calculate the difference between two dates in years, months, days, and business days. Add or subtract a duration from a date with month-clamping.
Instructions
Date Difference and Duration Calculator. Pure deterministic proleptic-Gregorian date math over UTC, with no clock/now dependency — every date is supplied by the caller. operation "diff" returns the calendar years/months/days gap between two dates, the direction (forward/backward/same), and absolute totals (days, weeks plus remainder, hours/minutes/seconds, and Mon-Fri business days, no holiday exclusion). operation "addDuration" / "subtractDuration" apply a signed years/months/weeks/days duration to a base date using month-clamp (Jan 31 + 1 month is Feb 28/29) and return the resulting date. Use this for days-between, business-day counts, or date arithmetic; use time_age_calculator for age/birthday math, time_date_calculator for weekend-skipping business-day arithmetic, and time_time_duration for HH:MM:SS clock-time math. Read-only, non-destructive, idempotent, offline-capable, rate-limited (60 req/min anonymous), no auth. Result is wrapped as operation plus data.
Input Schema
| Name | Required | Description | Default |
|---|---|---|---|
| operation | Yes | "diff": gap between two dates (needs from* and to*). "addDuration"/"subtractDuration": apply duration to a base date (needs year/month/day and duration). | |
| fromYear | No | Start-date year (proleptic Gregorian). Required when operation is diff. | |
| fromMonth | No | Start-date month 1-12. Required when operation is diff. | |
| fromDay | No | Start-date day 1-31; must be a real calendar date. Required when operation is diff. | |
| toYear | No | End-date year. Required when operation is diff. | |
| toMonth | No | End-date month 1-12. Required when operation is diff. | |
| toDay | No | End-date day 1-31. Required when operation is diff. | |
| year | No | Base-date year. Required when operation is addDuration or subtractDuration. | |
| month | No | Base-date month 1-12. Required when operation is addDuration or subtractDuration. | |
| day | No | Base-date day 1-31; must be a real calendar date. Required when operation is addDuration or subtractDuration. | |
| duration | No | Signed duration to apply. Required when operation is addDuration or subtractDuration. Each component defaults to 0 and may be negative. |
Output Schema
| Name | Required | Description | Default |
|---|---|---|---|
| operation | No | The operation that was run, echoed back (diff, addDuration, or subtractDuration). | |
| data | No | Result payload; shape depends on operation. |