Number of days between dates

This number-of-days calculator answers a household planning question that spreadsheets still get wrong: given two calendar dates, what is the day count, and do both endpoints count? You send two ISO days in year-month-day form and an endpoints mode of exclude or include. If either input is not a real Gregorian calendar day, the request fails with invalid_input and is not charged. Successful API calls cost $0.002.

What include versus exclude changes in the number of days

People type “number of days between two dates”, “how many days is my trip”, or “number of days calculator” when they want a single integer, but they do not all agree on whether the first day and the last day count. Hospital admissions, rental contracts, school absences, visa-stay tallies, and “days this offer is live” use the same fork. Same-day pairs therefore yield zero under exclude and one under include. Times of day, time zones, and business-day calendars are out of scope: a midnight-to-midnight civil day is the unit. A hotel stay from Monday check-in through Thursday check-out is three nights if you exclude both endpoints as a gap, and four calendar days if you include the arrival day through the departure day. This page makes the choice explicit with an endpoints field: exclude returns the open interval, which is the absolute difference of two Gregorian serial day numbers; include returns that difference plus one so both endpoints sit inside the count. Reversing the pair never changes the absolute days figure; only signed_days flips sign so a pipeline can keep chronological direction. Because the implementation never constructs a JavaScript Date, the same pair and the same mode always yield the same integer whether it runs in a Worker, a browser in Tokyo, or a test harness with TZ set to America/New_York. That reproducibility is why the landing exists next to, not instead of, a plain days-between tool that never offers the include switch.

How the two ISO dates and the endpoints mode are read

The required fields are start and end, each a real calendar day in YYYY-MM-DD form. When it is omitted the engine defaults to exclude, matching the usual nights-between or midnights-between reading. Each date must be a real Gregorian day: four-digit year, two-digit month, two-digit day, with February twenty-nine allowed only in a leap year. Years are limited to the inclusive range one through nine thousand nine hundred ninety-nine so four-digit ISO strings stay well defined. Classic checks include twenty twenty-four dash zero one dash zero one to twenty twenty-four dash zero one dash one one under exclude yielding ten days, and twenty twenty-four dash zero two dash twenty-eight to twenty twenty-four dash zero three dash zero one under include yielding three days across a leap day. Aliases from, date1, begin, and a are accepted for the first date; aliases to, date2, finish, and b are accepted for the second, so a form, a query string, or a spreadsheet column can reuse the contract. The optional endpoints field is a closed enum: exclude or include. Aliases mode, count, and include_endpoints are accepted for the same switch. Missing fields, empty strings, non-string types, malformed patterns, impossible months, and non-leap twenty-ninth of February fail with invalid_input that names the field. A value of endpoints that is not exclude or include fails the same way. On success the body echoes the canonical start and end strings, the resolved endpoints mode, days as the non-negative count, signed_days with chronological direction, year-month-day components of both dates, and a short formula string. Successful API requests cost $0.002; invalid input is not billed.

Where a number-of-days count with an endpoint switch shows up

Because this capability is a pure parse engine, the work runs entirely in your browser on this page, and through the API each successful lookup costs $0.002 while failed validation does not consume balance. Nothing is stored after the response returns.