curatedapi
Browse the docs

Guides

Finance

Excel functions

Late payments

E-invoices

Accounting

Number checks

VAT and GST

Billing and pricing

Money and currencies

Dates and time

Math

Unit conversion

Everyday

Health

Date difference API

Days, weeks, months, years and business days between two dates, or the exact time between two date-times across time zones and daylight saving changes.

POST https://api.curatedapi.com/v1/calc/date/difference

For two dates, returns the number of days (end minus start), the breakdown into years, months and days, and the number of business days. For two date-times, returns the exact elapsed time; each date-time needs a UTC offset or a time zone, and times that are skipped or repeated by daylight saving changes are reported instead of guessed.

Formula

days = end − start; Y-M-D: largest whole months not passing end, then days
  • Dates use the Gregorian calendar (ISO 8601). Adding months clamps to the month's last day (Jan 31 + 1 month = Feb 28 or 29).
  • Time zones come from the IANA time zone database in the pinned tzdata package; the version used is returned with each date-time result.
  • When end is before start, every count is negative.
  • include_end_date changes days, weeks and business_days; the years-months-days breakdown is always the exact span from start to end.
  • Leap seconds are not counted.

Inputs

Send numbers as strings to keep every digit. options sets precision and rounding (see numbers and rounding).

InputTypeDescription
start required string Start date (YYYY-MM-DD) or date-time (2026-03-29T01:30:00+01:00). At most 40 characters.
end required string End date or date-time, same kind as start. At most 40 characters.
timezone string IANA time zone for date-times without an offset, e.g. America/New_York.
include_end_date boolean
default False
Count the end date too (so Monday to Friday is 5 days, like spreadsheet NETWORKDAYS).
weekend sat_sun | fri_sat | sun | fri | none
default sat_sun
Days that are not business days. Options: sat_sun: Saturday and Sunday; fri_sat: Friday and Saturday; sun: Sunday only; fri: Friday only; none: no weekend days
holidays list of date (YYYY-MM-DD) Dates that are not business days. Up to 1000 items.
options.rounding half_even | half_up | half_down | up | down | ceiling | floor Rounding mode applied once to each result. Default half_even.
options.decimals integer Round results to this many digits after the decimal point.
options.significant_digits integer Round results to this many significant digits.

Result

Under result in the answer, next to exactness, precision, inputs, formula, references and warnings.

ResultTypeDescription
daysintegerDays from start to end (negative if end is earlier); with include_end_date the end day is counted too.
weeksintegerWhole weeks in days.
remaining_daysintegerDays left after the whole weeks.
yearsintegerYears in the years-months-days breakdown.
monthsintegerMonths in the breakdown.
calendar_daysintegerDays in the breakdown.
total_monthsintegerWhole months between the dates.
business_daysintegerBusiness days from start up to (not including) end, or including end when include_end_date is true.
start_weekdaystringDay of the week of start.
end_weekdaystringDay of the week of end.
total_secondsdecimal (string)Exact elapsed seconds (date-times).
total_minutesdecimal (string)Elapsed minutes (date-times).
total_hoursdecimal (string)Elapsed hours (date-times).
total_daysdecimal (string)Elapsed days of 24 hours (date-times).
elapsed_daysintegerWhole days in the elapsed time (date-times).
elapsed_hoursintegerHours after the whole days (date-times).
elapsed_minutesintegerMinutes after the whole hours (date-times).
elapsed_secondsstringSeconds after the whole minutes, exactly (date-times).
tz_databasestringTime zone database version used.

Examples

Days until Christmas 2026

Requestcurl
curl https://api.curatedapi.com/v1/calc/date/difference \
  -H "Authorization: Bearer $CURATEDAPI_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "start": "2026-01-01",
    "end": "2026-12-25"
  }'
200 OKResponse
{
  "calculator": "date/difference@1",
  "result": {
    "days": 358,
    "weeks": 51,
    "remaining_days": 1,
    "years": 0,
    "months": 11,
    "calendar_days": 24,
    "total_months": 11,
    "business_days": 256,
    "start_weekday": "Thursday",
    "end_weekday": "Friday"
  },
  "exactness": {},
  "precision": {
    "rounding": "half_even",
    "significant_digits": 15
  },
  "inputs": {
    "start": "2026-01-01",
    "end": "2026-12-25",
    "include_end_date": false,
    "weekend": "sat_sun"
  },
  "formula": "days = end − start; Y-M-D: largest whole months not passing end, then days",
  "references": [
    {
      "title": "ISO 8601 date and time format",
      "url": "https://www.iso.org/iso-8601-date-and-time-format.html"
    },
    {
      "title": "IANA Time Zone Database",
      "url": "https://www.iana.org/time-zones"
    }
  ],
  "warnings": []
}

Working days in a week, inclusive

Requestcurl
curl https://api.curatedapi.com/v1/calc/date/difference \
  -H "Authorization: Bearer $CURATEDAPI_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "start": "2026-10-19",
    "end": "2026-10-23",
    "include_end_date": true
  }'
200 OKResponse
{
  "calculator": "date/difference@1",
  "result": {
    "days": 5,
    "weeks": 0,
    "remaining_days": 5,
    "years": 0,
    "months": 0,
    "calendar_days": 4,
    "total_months": 0,
    "business_days": 5,
    "start_weekday": "Monday",
    "end_weekday": "Friday"
  },
  "exactness": {},
  "precision": {
    "rounding": "half_even",
    "significant_digits": 15
  },
  "inputs": {
    "start": "2026-10-19",
    "end": "2026-10-23",
    "include_end_date": true,
    "weekend": "sat_sun"
  },
  "formula": "days = end − start; Y-M-D: largest whole months not passing end, then days",
  "references": [
    {
      "title": "ISO 8601 date and time format",
      "url": "https://www.iso.org/iso-8601-date-and-time-format.html"
    },
    {
      "title": "IANA Time Zone Database",
      "url": "https://www.iana.org/time-zones"
    }
  ],
  "warnings": []
}

Across a daylight saving change

Requestcurl
curl https://api.curatedapi.com/v1/calc/date/difference \
  -H "Authorization: Bearer $CURATEDAPI_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "start": "2026-03-28T12:00:00",
    "end": "2026-03-29T12:00:00",
    "timezone": "Europe/Berlin"
  }'
200 OKResponse
{
  "calculator": "date/difference@1",
  "result": {
    "total_seconds": "82800",
    "total_minutes": "1380",
    "total_hours": "23",
    "total_days": "0.958333333333333",
    "elapsed_days": 0,
    "elapsed_hours": 23,
    "elapsed_minutes": 0,
    "elapsed_seconds": "0",
    "tz_database": "tzdata 2026.6 (IANA 2026f)"
  },
  "exactness": {
    "total_seconds": "exact",
    "total_minutes": "exact",
    "total_hours": "exact",
    "total_days": "rounded"
  },
  "precision": {
    "rounding": "half_even",
    "significant_digits": 15
  },
  "inputs": {
    "start": "2026-03-28T12:00:00",
    "end": "2026-03-29T12:00:00",
    "timezone": "Europe/Berlin",
    "include_end_date": false,
    "weekend": "sat_sun"
  },
  "formula": "days = end − start; Y-M-D: largest whole months not passing end, then days",
  "references": [
    {
      "title": "ISO 8601 date and time format",
      "url": "https://www.iso.org/iso-8601-date-and-time-format.html"
    },
    {
      "title": "IANA Time Zone Database",
      "url": "https://www.iana.org/time-zones"
    }
  ],
  "warnings": []
}

References

Results follow each calculator's documented rules and the sources listed. They are not financial, tax or legal advice. Check that the rules fit your case before you rely on a result. See the terms.

Errors share one format; see errors. Billing, retries and batches work the same for every endpoint.