curatedapi

Add or subtract time from a date

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.

Start date (YYYY-MM-DD) or date-time. At most 40 characters.
Add or subtract. Options: add: add; subtract: subtract
Years to add.
Months to add.
Weeks to add.
Days to add.
Business days to add (alone, with a plain date).
Hours of elapsed time to add (date-times).
Minutes of elapsed time to add (date-times).
Seconds of elapsed time to add (date-times).
IANA time zone for a date-time start without an offset.
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
Dates that are not business days. Up to 1000 items. One per line, or separated by commas.

Examples

Result: Subtract a year from a leap day

Result
The resulting date or date-time.
2027-02-28
Weekday
Day of the week of the result.
Sunday

Calculator date/add@1.

How it is calculated

months first (clamped to month end), then weeks and days, then elapsed time

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.

  • 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.

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.

Use it from your code

POST /v1/calc/date/addVersion 1
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"
  }'
The same call in Python
import os

import requests

payload = {
    "start": "2028-02-29",
    "years": 1,
    "operation": "subtract",
}
response = requests.post(
    "https://api.curatedapi.com/v1/calc/date/add",
    headers={"Authorization": f"Bearer {os.environ['CURATEDAPI_KEY']}"},
    json=payload,
    timeout=10,
)
print(response.json()["result"])
The same call in JavaScript
const payload = {
    "start": "2028-02-29",
    "years": 1,
    "operation": "subtract",
};
const response = await fetch("https://api.curatedapi.com/v1/calc/date/add", {
  method: "POST",
  headers: {
    Authorization: `Bearer ${process.env.CURATEDAPI_KEY}`,
    "Content-Type": "application/json",
  },
  body: JSON.stringify(payload),
});
console.log((await response.json()).result);

MCP tool calc_date_add at https://mcp.curatedapi.com. Inputs, outputs and errors in the API reference.

Put it on your website

<div data-curatedapi-widget="date/add" data-key="capi_public_…"></div>
<script src="https://widgets.curatedapi.com/v1/widget.js" async></script>

Use a public key registered for your site. Calculations are billed like API calls. How widgets work.

Related calculators

Add this calculator to your website

Paste two lines into your page and your visitors get this calculator. Each use counts as one call on your plan, the same as the API.

Free for up to 1,000 uses a month. 50,000 uses a month cost $9.00 on the Starter plan.