Skip to content
Calcadian logoCalcadian

Calcadian API

Date, business-day and duration calculations over HTTP, with a deterministic engine and explicit holiday handling.

The commercial API is in prelaunch. These pages describe what is built and testable today. API key creation is currently closed and the gateway is gated behind an internal feature flag.

Base URL

https://calcadian.com/api/v1

Every operation is a POST to {base}/{operation} with a JSON object body and a JSON object response. The current API version is v1.

Response shape

json
{
  "data": { "total_days": 73 },
  "meta": { "request_id": "req_9f2c41a7be03d5710c8e2b44", "api_version": "v1" }
}

Errors use one standard shape. See Errors.

Implemented operations

  • POST /date-difference: Calendar days, weeks and years/months/days between two dates.
  • POST /add-days: Add or subtract days, weeks, months or years from a date.
  • POST /business-days-between: Count working days between two dates using a working week and holiday calendar.
  • POST /add-business-days: Move forwards or backwards by a number of working days.
  • POST /is-business-day: Check whether a date is a working day, and find the neighbouring working days.
  • POST /age: Exact age in years, months and days, plus totals and the next birthday.
  • POST /time-duration: Duration between two clock times, with optional dates, overnight shifts and unpaid breaks.
  • POST /week-number: ISO-8601 week number, week year and the week's start and end dates.
  • POST /day-of-week: Weekday name and ISO weekday number for a date.
  • POST /unix-timestamp: Convert between Unix seconds and ISO-8601. Supply exactly one of timestamp or date_time.

Nothing else is part of the v1 contract. Batch processing, reports and white-label are not implemented and are not documented here.

Machine-readable specification

The OpenAPI 3.1 document is generated from the same operation catalog that powers the gateway: /openapi.json.

Where to start