Skip to content
Calcadian logoCalcadian

Calcadian API

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

Every plan can create an API key. Free includes 500 requests a month. Create a key on the API keys page of your dashboard, then follow the Quickstart. Higher limits are listed under Limits.

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