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
- Version 1
- MCP tool
calc_date_difference - Try it in the browser
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).
| Input | Type | Description |
|---|---|---|
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.
| Result | Type | Description |
|---|---|---|
days | integer | Days from start to end (negative if end is earlier); with include_end_date the end day is counted too. |
weeks | integer | Whole weeks in days. |
remaining_days | integer | Days left after the whole weeks. |
years | integer | Years in the years-months-days breakdown. |
months | integer | Months in the breakdown. |
calendar_days | integer | Days in the breakdown. |
total_months | integer | Whole months between the dates. |
business_days | integer | Business days from start up to (not including) end, or including end when include_end_date is true. |
start_weekday | string | Day of the week of start. |
end_weekday | string | Day of the week of end. |
total_seconds | decimal (string) | Exact elapsed seconds (date-times). |
total_minutes | decimal (string) | Elapsed minutes (date-times). |
total_hours | decimal (string) | Elapsed hours (date-times). |
total_days | decimal (string) | Elapsed days of 24 hours (date-times). |
elapsed_days | integer | Whole days in the elapsed time (date-times). |
elapsed_hours | integer | Hours after the whole days (date-times). |
elapsed_minutes | integer | Minutes after the whole hours (date-times). |
elapsed_seconds | string | Seconds after the whole minutes, exactly (date-times). |
tz_database | string | Time zone database version used. |
Examples
Days until Christmas 2026
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"
}'
{
"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
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
}'
{
"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
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"
}'
{
"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.