API

The same calculation engine the site uses, over HTTP. Every operation is a POST with a JSON body and a JSON response.

Quickstart

Create a key in your dashboard, then send a request. The base URL is https://calcadian.com/api/v1.

curl https://calcadian.com/api/v1/date-difference \
  -H "X-API-Key: $CALCADIAN_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"start_date":"2026-01-01","end_date":"2026-03-14"}'

A successful response wraps the result in data and adds a request id:

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

Authentication

Send your key in a header, either X-API-Key: ck_live_... or Authorization: Bearer ck_live_.... Keys are never accepted in the query string, because URLs end up in browser history, proxy logs and referrer headers.

Calcadian stores a hash of each key, not the key itself. The full value is shown once when you create it. If you lose it, revoke the key and create a new one.

API keys

Create, name and revoke keys in the dashboard under API keys.
Revoking takes effect immediately for new requests.
Keys do not carry their own quota. All keys on an account share the account's monthly allowance.
Use separate keys for separate environments so you can revoke one without breaking the other.

Quotas and rate limits

API quotas and limits by plan
	Free	Pro	Business
Requests a month	500	10,000	100,000
Requests a minute	30	120	600
Keys	1	1	5
Request history	Not included	30 days	90 days

The monthly quota resets at the start of each calendar month in UTC.
The per-minute limit is burst protection and is measured per account, not per key.
Over quota returns a quota error; over the burst limit returns a rate-limit error. Neither affects your widgets or the site calculators.

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.

Field-by-field reference, request and response examples for each operation: developer documentation.

Errors

Every failure uses the same shape, so you can handle it in one place.

{
  "error": {
    "code": "validation_error",
    "message": "end_date must be a valid ISO date.",
    "request_id": "req_9f2c41a7be03d5710c8e2b44"
  }
}

Include the request_id if you contact us about a specific failure. The full code list is in the error reference.

Versioning

The current version is v1 and it is part of the path. Additive changes, such as a new optional field or a new operation, ship inside v1. Anything that would break an existing integration would ship as a new version path instead.

API Playground

The playground runs real, metered requests with your own key, so a call made there counts against your monthly quota exactly like any other.