Calculations
Every operation in the v1 contract. Anything not on this page is not implemented.
Conventions
- All operations are
POSTwith a JSON object body. - Dates are strict
YYYY-MM-DDdate-only strings. Impossible dates such as2026-02-30are rejected with400 INVALID_DATE, never rolled forward. - Unknown fields are rejected rather than ignored, so a typo never silently changes a result.
- Business-day operations also accept the shared calendar fields, described on the Business Calendars page.
On this page
- Date difference
/date-difference - Add days
/add-days - Business days between
/business-days-between - Add business days
/add-business-days - Is business day
/is-business-day - Age
/age - Time duration
/time-duration - ISO week number
/week-number - Day of week
/day-of-week - Unix timestamp
/unix-timestamp
Date difference
Calendar days, weeks and years/months/days between two dates.
POST https://calcadian.com/api/v1/date-difference| Field | Type | Required | Description |
|---|---|---|---|
| start_date | string (YYYY-MM-DD) | Yes | Start date, YYYY-MM-DD. |
| end_date | string (YYYY-MM-DD) | Yes | End date, YYYY-MM-DD. |
| include_end_date | boolean | No | Add the end date as one extra day. By default the span runs from the start date to the end date, so the end date closes the span and the start date is not counted. Default: false. |
// request
{
"start_date": "2026-01-01",
"end_date": "2026-03-15"
}
// response.data
{
"start_date": "2026-01-01",
"end_date": "2026-03-15",
"include_end_date": false,
"total_days": 73,
"weeks": 10,
"remainder_days": 3,
"years": 0,
"months": 2,
"days": 14
}Errors: INVALID_REQUESTINVALID_JSONUNKNOWN_FIELDMISSING_API_KEYINVALID_API_KEYREVOKED_API_KEYEXPIRED_API_KEYAPI_KEY_IN_QUERY_STRINGENVIRONMENT_MISMATCHPAYLOAD_TOO_LARGERATE_LIMIT_EXCEEDEDAPI_QUOTA_EXCEEDEDINTERNAL_ERRORSERVICE_UNAVAILABLEINVALID_DATERANGE_TOO_LARGEVALIDATION_ERROR
Add days
Add or subtract days, weeks, months or years from a date.
POST https://calcadian.com/api/v1/add-days| Field | Type | Required | Description |
|---|---|---|---|
| start_date | string (YYYY-MM-DD) | Yes | Start date, YYYY-MM-DD. |
| days | integer | Yes | Amount to add. Negative values subtract. |
| unit | string | No | Unit for the amount. Default: days. One of: "days", "weeks", "months", "years". |
| skip_weekends | boolean | No | Skip Saturdays and Sundays. Ignores public holidays; use add-business-days for holiday-aware maths. Default: false. |
// request
{
"start_date": "2026-01-01",
"days": 45
}
// response.data
{
"start_date": "2026-01-01",
"days": 45,
"unit": "days",
"skip_weekends": false,
"result_date": "2026-02-15",
"weekday": "Sunday"
}Errors: INVALID_REQUESTINVALID_JSONUNKNOWN_FIELDMISSING_API_KEYINVALID_API_KEYREVOKED_API_KEYEXPIRED_API_KEYAPI_KEY_IN_QUERY_STRINGENVIRONMENT_MISMATCHPAYLOAD_TOO_LARGERATE_LIMIT_EXCEEDEDAPI_QUOTA_EXCEEDEDINTERNAL_ERRORSERVICE_UNAVAILABLEINVALID_DATEVALIDATION_ERROR
Business days between
Count working days between two dates using a working week and holiday calendar.
POST https://calcadian.com/api/v1/business-days-between| Field | Type | Required | Description |
|---|---|---|---|
| start_date | string (YYYY-MM-DD) | Yes | Start date, YYYY-MM-DD. |
| end_date | string (YYYY-MM-DD) | Yes | End date, YYYY-MM-DD. |
| include_start_date | boolean | No | Count the start date when it is a working day. Defaults to true, so a working-day span includes both endpoints. Default: true. |
| include_end_date | boolean | No | Count the end date when it is a working day. Defaults to true, so a working-day span includes both endpoints. Default: true. |
| detailed | boolean | No | Return a day-by-day trace. Only available for ranges of 400 days or fewer. Default: false. |
| business_calendar_id | string (uuid) | No | Id of a saved Business Calendar owned by the API key's account. When supplied, all other calendar fields are ignored. Requires the Business Calendars feature on the account. |
| country_code | string | No | Two-letter ISO 3166-1 country code used for public holidays. Default: US. |
| subdivision_code | string | No | Region/state code within the country. If supplied and not supported for that country, the request fails with 422 INVALID_SUBDIVISION. There is no silent fallback to national holidays. |
| working_days | integer[] | No | ISO weekday numbers that count as working days. 1 = Monday, 7 = Sunday. Defaults to [1,2,3,4,5]. |
| include_public_holidays | boolean | No | Whether public holidays for the country/subdivision are treated as non-working days. Default: true. |
// request
{
"start_date": "2026-01-01",
"end_date": "2026-01-31",
"country_code": "US"
}
// response.data
{
"start_date": "2026-01-01",
"end_date": "2026-01-31",
"business_days": 20,
"summary": {
"calendar_days_elapsed": 31,
"working_days_counted": 20,
"non_working_weekdays_skipped": 9,
"public_holidays_skipped": 2,
"custom_holidays_skipped": 0,
"excluded_dates_skipped": 0,
"reversed": false,
"provider": "date-holidays",
"provider_version": "3.x"
}
}Errors: INVALID_REQUESTINVALID_JSONUNKNOWN_FIELDMISSING_API_KEYINVALID_API_KEYREVOKED_API_KEYEXPIRED_API_KEYAPI_KEY_IN_QUERY_STRINGENVIRONMENT_MISMATCHPAYLOAD_TOO_LARGERATE_LIMIT_EXCEEDEDAPI_QUOTA_EXCEEDEDINTERNAL_ERRORSERVICE_UNAVAILABLEINVALID_COUNTRYINVALID_SUBDIVISIONBUSINESS_CALENDAR_NOT_FOUNDFEATURE_NOT_AVAILABLEINVALID_DATERANGE_TOO_LARGEVALIDATION_ERROR
Add business days
Move forwards or backwards by a number of working days.
POST https://calcadian.com/api/v1/add-business-days| Field | Type | Required | Description |
|---|---|---|---|
| start_date | string (YYYY-MM-DD) | Yes | Start date, YYYY-MM-DD. |
| days | integer | Yes | Business days to add. Negative values move backwards. |
| include_start_date | boolean | No | Count the start date as day one. Default: false. |
| detailed | boolean | No | Return a day-by-day trace. Default: false. |
| business_calendar_id | string (uuid) | No | Id of a saved Business Calendar owned by the API key's account. When supplied, all other calendar fields are ignored. Requires the Business Calendars feature on the account. |
| country_code | string | No | Two-letter ISO 3166-1 country code used for public holidays. Default: US. |
| subdivision_code | string | No | Region/state code within the country. If supplied and not supported for that country, the request fails with 422 INVALID_SUBDIVISION. There is no silent fallback to national holidays. |
| working_days | integer[] | No | ISO weekday numbers that count as working days. 1 = Monday, 7 = Sunday. Defaults to [1,2,3,4,5]. |
| include_public_holidays | boolean | No | Whether public holidays for the country/subdivision are treated as non-working days. Default: true. |
// request
{
"start_date": "2026-01-01",
"days": 10,
"country_code": "GB"
}
// response.data
{
"start_date": "2026-01-01",
"days": 10,
"result_date": "2026-01-16",
"summary": {
"calendar_days_elapsed": 15,
"working_days_counted": 10,
"non_working_weekdays_skipped": 4,
"public_holidays_skipped": 1,
"custom_holidays_skipped": 0,
"excluded_dates_skipped": 0,
"reversed": false,
"provider": "date-holidays",
"provider_version": "3.x"
}
}Errors: INVALID_REQUESTINVALID_JSONUNKNOWN_FIELDMISSING_API_KEYINVALID_API_KEYREVOKED_API_KEYEXPIRED_API_KEYAPI_KEY_IN_QUERY_STRINGENVIRONMENT_MISMATCHPAYLOAD_TOO_LARGERATE_LIMIT_EXCEEDEDAPI_QUOTA_EXCEEDEDINTERNAL_ERRORSERVICE_UNAVAILABLEINVALID_COUNTRYINVALID_SUBDIVISIONBUSINESS_CALENDAR_NOT_FOUNDFEATURE_NOT_AVAILABLEINVALID_DATEVALIDATION_ERROR
Is business day
Check whether a date is a working day, and find the neighbouring working days.
POST https://calcadian.com/api/v1/is-business-day| Field | Type | Required | Description |
|---|---|---|---|
| date | string (YYYY-MM-DD) | Yes | Date to check, YYYY-MM-DD. |
| business_calendar_id | string (uuid) | No | Id of a saved Business Calendar owned by the API key's account. When supplied, all other calendar fields are ignored. Requires the Business Calendars feature on the account. |
| country_code | string | No | Two-letter ISO 3166-1 country code used for public holidays. Default: US. |
| subdivision_code | string | No | Region/state code within the country. If supplied and not supported for that country, the request fails with 422 INVALID_SUBDIVISION. There is no silent fallback to national holidays. |
| working_days | integer[] | No | ISO weekday numbers that count as working days. 1 = Monday, 7 = Sunday. Defaults to [1,2,3,4,5]. |
| include_public_holidays | boolean | No | Whether public holidays for the country/subdivision are treated as non-working days. Default: true. |
// request
{
"date": "2026-01-01",
"country_code": "US"
}
// response.data
{
"date": "2026-01-01",
"is_business_day": false,
"weekday": 4,
"reason": "public_holiday",
"label": "New Year's Day",
"next_business_day": "2026-01-02",
"previous_business_day": "2025-12-31"
}Errors: INVALID_REQUESTINVALID_JSONUNKNOWN_FIELDMISSING_API_KEYINVALID_API_KEYREVOKED_API_KEYEXPIRED_API_KEYAPI_KEY_IN_QUERY_STRINGENVIRONMENT_MISMATCHPAYLOAD_TOO_LARGERATE_LIMIT_EXCEEDEDAPI_QUOTA_EXCEEDEDINTERNAL_ERRORSERVICE_UNAVAILABLEINVALID_COUNTRYINVALID_SUBDIVISIONBUSINESS_CALENDAR_NOT_FOUNDFEATURE_NOT_AVAILABLEINVALID_DATEVALIDATION_ERROR
Age
Exact age in years, months and days, plus totals and the next birthday.
POST https://calcadian.com/api/v1/age| Field | Type | Required | Description |
|---|---|---|---|
| birth_date | string (YYYY-MM-DD) | Yes | Date of birth, YYYY-MM-DD. |
| as_of_date | string (YYYY-MM-DD) | No | Date to calculate the age at. Defaults to today (UTC). |
// request
{
"birth_date": "1990-05-20",
"as_of_date": "2026-01-01"
}
// response.data
{
"birth_date": "1990-05-20",
"as_of_date": "2026-01-01",
"years": 35,
"months": 7,
"days": 12,
"total_months": 427,
"total_weeks": 1858,
"total_days": 13010,
"born_on": "Sunday",
"next_birthday": "2026-05-20",
"days_until_next_birthday": 139
}Errors: INVALID_REQUESTINVALID_JSONUNKNOWN_FIELDMISSING_API_KEYINVALID_API_KEYREVOKED_API_KEYEXPIRED_API_KEYAPI_KEY_IN_QUERY_STRINGENVIRONMENT_MISMATCHPAYLOAD_TOO_LARGERATE_LIMIT_EXCEEDEDAPI_QUOTA_EXCEEDEDINTERNAL_ERRORSERVICE_UNAVAILABLEINVALID_DATEVALIDATION_ERROR
Time duration
Duration between two clock times, with optional dates, overnight shifts and unpaid breaks.
POST https://calcadian.com/api/v1/time-duration| Field | Type | Required | Description |
|---|---|---|---|
| start_time | string (HH:MM) | Yes | 24-hour HH:MM. |
| end_time | string (HH:MM) | Yes | 24-hour HH:MM. |
| start_date | string (YYYY-MM-DD) | No | Optional start date, YYYY-MM-DD. |
| end_date | string (YYYY-MM-DD) | No | Optional end date, YYYY-MM-DD. |
| next_day | boolean | No | End time falls on the following day. Default: false. |
| break_minutes | integer | No | Unpaid break subtracted from the total. Default: 0. |
// request
{
"start_time": "09:00",
"end_time": "17:30",
"break_minutes": 30
}
// response.data
{
"start_time": "09:00",
"end_time": "17:30",
"break_minutes": 30,
"total_minutes": 480,
"hours": 8,
"minutes": 0,
"decimal_hours": 8
}Errors: INVALID_REQUESTINVALID_JSONUNKNOWN_FIELDMISSING_API_KEYINVALID_API_KEYREVOKED_API_KEYEXPIRED_API_KEYAPI_KEY_IN_QUERY_STRINGENVIRONMENT_MISMATCHPAYLOAD_TOO_LARGERATE_LIMIT_EXCEEDEDAPI_QUOTA_EXCEEDEDINTERNAL_ERRORSERVICE_UNAVAILABLEINVALID_DATEVALIDATION_ERROR
ISO week number
ISO-8601 week number, week year and the week's start and end dates.
POST https://calcadian.com/api/v1/week-number| Field | Type | Required | Description |
|---|---|---|---|
| date | string (YYYY-MM-DD) | Yes | Date, YYYY-MM-DD. |
// request
{
"date": "2026-01-01"
}
// response.data
{
"date": "2026-01-01",
"iso_week": 1,
"iso_week_year": 2026,
"weekday": 4,
"week_start": "2025-12-29",
"week_end": "2026-01-04"
}Errors: INVALID_REQUESTINVALID_JSONUNKNOWN_FIELDMISSING_API_KEYINVALID_API_KEYREVOKED_API_KEYEXPIRED_API_KEYAPI_KEY_IN_QUERY_STRINGENVIRONMENT_MISMATCHPAYLOAD_TOO_LARGERATE_LIMIT_EXCEEDEDAPI_QUOTA_EXCEEDEDINTERNAL_ERRORSERVICE_UNAVAILABLEINVALID_DATEVALIDATION_ERROR
Day of week
Weekday name and ISO weekday number for a date.
POST https://calcadian.com/api/v1/day-of-week| Field | Type | Required | Description |
|---|---|---|---|
| date | string (YYYY-MM-DD) | Yes | Date, YYYY-MM-DD. |
// request
{
"date": "2026-01-01"
}
// response.data
{
"date": "2026-01-01",
"weekday": "Thursday",
"iso_weekday": 4
}Errors: INVALID_REQUESTINVALID_JSONUNKNOWN_FIELDMISSING_API_KEYINVALID_API_KEYREVOKED_API_KEYEXPIRED_API_KEYAPI_KEY_IN_QUERY_STRINGENVIRONMENT_MISMATCHPAYLOAD_TOO_LARGERATE_LIMIT_EXCEEDEDAPI_QUOTA_EXCEEDEDINTERNAL_ERRORSERVICE_UNAVAILABLEINVALID_DATE
Unix timestamp
Convert between Unix seconds and ISO-8601. Supply exactly one of timestamp or date_time.
POST https://calcadian.com/api/v1/unix-timestamp| Field | Type | Required | Description |
|---|---|---|---|
| timestamp | number | No | Seconds since the Unix epoch. Values above 1e11 are read as milliseconds. |
| date_time | string | No | ISO-8601 date (YYYY-MM-DD) or date-time to convert. |
// request
{
"timestamp": 1767225600
}
// response.data
{
"unix_seconds": 1767225600,
"iso_utc": "2026-01-01T00:00:00.000Z",
"date": "2026-01-01",
"weekday": "Thursday"
}Errors: INVALID_REQUESTINVALID_JSONUNKNOWN_FIELDMISSING_API_KEYINVALID_API_KEYREVOKED_API_KEYEXPIRED_API_KEYAPI_KEY_IN_QUERY_STRINGENVIRONMENT_MISMATCHPAYLOAD_TOO_LARGERATE_LIMIT_EXCEEDEDAPI_QUOTA_EXCEEDEDINTERNAL_ERRORSERVICE_UNAVAILABLEVALIDATION_ERROR