Add or subtract time from a date API
Add or subtract years, months, weeks, days, business days or hours to a date or date-time, with month-end and daylight-saving rules spelled out.
POST https://api.curatedapi.com/v1/calc/date/add
- Version 1
- MCP tool
calc_date_add - Try it in the browser
Calendar amounts (years, months, weeks, days) move the date on the calendar, keeping the clock time; hours, minutes and seconds are then added as elapsed time. So adding 1 day across a daylight saving change keeps 09:00 at 09:00, while adding 24 hours may not. Month additions that land on a day that does not exist use the month's last day, and the response says so.
Formula
months first (clamped to month end), then weeks and days, then elapsed time
- 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.
- Business days skip the weekend days and holidays; the start day is 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. At most 40 characters. |
operation |
add | subtract default add |
Add or subtract. Options: add: add; subtract: subtract |
years |
integer default 0 |
Years to add. Allowed: >= 0 and <= 9999. |
months |
integer default 0 |
Months to add. Allowed: >= 0 and <= 120000. |
weeks |
integer default 0 |
Weeks to add. Allowed: >= 0 and <= 600000. |
days |
integer default 0 |
Days to add. Allowed: >= 0 and <= 4000000. |
business_days |
integer | Business days to add (alone, with a plain date). Allowed: >= 0 and <= 25000. |
hours |
integer default 0 |
Hours of elapsed time to add (date-times). Allowed: >= 0 and <= 100000000. |
minutes |
integer default 0 |
Minutes of elapsed time to add (date-times). Allowed: >= 0 and <= 100000000. |
seconds |
decimal (string) default 0 |
Seconds of elapsed time to add (date-times). Allowed: >= 0 and <= 10000000000. |
timezone |
string | IANA time zone for a date-time start without an offset. |
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. |
Result
Under result in the answer, next to exactness, precision, inputs, formula, references and warnings.
| Result | Type | Description |
|---|---|---|
result | string | The resulting date or date-time. |
weekday | string | Day of the week of the result. |
result_utc | string | The result in UTC (date-times). |
tz_database | string | Time zone database version used. |
Examples
Month-end clamping
curl https://api.curatedapi.com/v1/calc/date/add \
-H "Authorization: Bearer $CURATEDAPI_KEY" \
-H "Content-Type: application/json" \
-d '{
"start": "2026-01-31",
"months": 1
}'
{
"calculator": "date/add@1",
"result": {
"result": "2026-02-28",
"weekday": "Saturday"
},
"exactness": {},
"precision": null,
"inputs": {
"start": "2026-01-31",
"operation": "add",
"years": 0,
"months": 1,
"weeks": 0,
"days": 0,
"hours": 0,
"minutes": 0,
"seconds": "0",
"weekend": "sat_sun"
},
"formula": "months first (clamped to month end), then weeks and days, then elapsed time",
"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": [
{
"code": "END_OF_MONTH_CLAMPED",
"message": "Day 31 does not exist in February 2026; the last day of the month, 2026-02-28, was used."
}
]
}
Ten business days
curl https://api.curatedapi.com/v1/calc/date/add \
-H "Authorization: Bearer $CURATEDAPI_KEY" \
-H "Content-Type: application/json" \
-d '{
"start": "2026-10-16",
"business_days": 10
}'
{
"calculator": "date/add@1",
"result": {
"result": "2026-10-30",
"weekday": "Friday"
},
"exactness": {},
"precision": null,
"inputs": {
"start": "2026-10-16",
"operation": "add",
"years": 0,
"months": 0,
"weeks": 0,
"days": 0,
"business_days": 10,
"hours": 0,
"minutes": 0,
"seconds": "0",
"weekend": "sat_sun"
},
"formula": "months first (clamped to month end), then weeks and days, then elapsed time",
"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": []
}
Subtract a year from a leap day
curl https://api.curatedapi.com/v1/calc/date/add \
-H "Authorization: Bearer $CURATEDAPI_KEY" \
-H "Content-Type: application/json" \
-d '{
"start": "2028-02-29",
"years": 1,
"operation": "subtract"
}'
{
"calculator": "date/add@1",
"result": {
"result": "2027-02-28",
"weekday": "Sunday"
},
"exactness": {},
"precision": null,
"inputs": {
"start": "2028-02-29",
"operation": "subtract",
"years": 1,
"months": 0,
"weeks": 0,
"days": 0,
"hours": 0,
"minutes": 0,
"seconds": "0",
"weekend": "sat_sun"
},
"formula": "months first (clamped to month end), then weeks and days, then elapsed time",
"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": [
{
"code": "END_OF_MONTH_CLAMPED",
"message": "Day 29 does not exist in February 2027; the last day of the month, 2027-02-28, was used."
}
]
}
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.