Date difference in years, months and days

It also reports direction and the signed total number of days. Because both dates are supplied directly, the answer never changes with the current time. Strict YYYY-MM-DD validation, proleptic Gregorian calendar rules, and timezone-independent arithmetic make the same request reproducible in a browser, an API workflow, a spreadsheet integration, or an automated test.

How the years, months, and days breakdown is calculated

The calculator treats the interval as a calendar duration, not as a decimal conversion of elapsed days. It begins at the earlier date and finds the greatest number of complete calendar months that can be added without passing the later date. That month count is then separated into complete years and the remaining months. Finally, the days field is the exact number of calendar days between that intermediate anniversary and the later date. For example, a span does not gain another month merely because it contains thirty days; the relevant question is whether the next calendar-month anniversary has arrived. This approach preserves the familiar meaning of years and months across months of different lengths. The response also includes total_days, which is a separate signed ordinal difference. Use that field when you need a pure day count, and use years, months, and days when you need a human-readable calendar breakdown. The components are nonnegative even for reversed dates, while direction and total_days preserve the input order.

Month ends, leap years, reversed dates, and UTC determinism

Calendar boundaries need explicit rules because not every day exists in every month. When a calendar-month step lands in a shorter month, the day is clamped to that month’s final valid day. January 31 advanced by one month therefore reaches February 28 in a common year or February 29 in a leap year. The algorithm then checks for overshoot before accepting the completed-month count, so a boundary never rounds upward accidentally. Leap years follow the Gregorian rule: years divisible by four are leap years, except century years unless they are divisible by four hundred. If the second date precedes the first, the calculator measures the same component magnitude in chronological order, labels the direction backward, and makes total_days negative. Equal inputs return zero for every numeric field and use the zero direction. All arithmetic operates on date-only integer fields. It does not construct a JavaScript Date, inspect a timezone, apply daylight-saving changes, call a network service, read the clock, or use locale parsing. That makes results stable across machines and repeated runs.

Choosing inputs and using the output correctly

Provide from and to as explicit strings in YYYY-MM-DD format, including leading zeroes for months and days. Calendar years from 0001 through 9999 are supported. Invalid dates such as 2023-02-29, missing fields, timestamps, regional forms such as 03/04/2025, and natural-language phrases are rejected instead of guessed. In the response, years, months, and days describe a sequential calendar duration from the chronologically earlier date to the later one. They should be read together: do not independently convert the months to a fixed number of days, because month lengths vary. The signed total_days field is useful for ordering, deadlines, and systems that need one scalar value. Direction states whether to is forward from, backward from, or equal to from. Common uses include displaying account tenure, documenting project spans, comparing historical dates, and building deterministic contract or reporting calculations. The API request price is $0.002. Since the calculation requires two explicit dates and never substitutes today, callers that want an age as of a particular day should pass that reference day deliberately and store it with their result.