📖 ad-bs API

Read-only · unauthenticated · JSON. Machine-readable schema: OpenAPI 3.1.

envelopeSuccess → { "ok": true, "data": … } · Failure → { "ok": false, "error": "slug", "message": "…" } with a proper 4xx status. Responses are never malformed; a date outside the dataset returns 404 out_of_range with the valid range.

date inputsLenient everywhere: 2026-07-09, 20260709, 2026_07_09, 2026/07/09, 2026-07-09T13:45:00Z — separators optional, time stripped.

Endpoints

route	params	description
`GET /api/v1/convert`	`ad` \| `bs`	Convert one date. Returns the full entry: both dates, weekday, human forms, divergence (both directions).
`GET /api/v1/today`	`tz?`	Today’s entry. `tz` = IANA name or `+HH:MM`; default `Asia/Kathmandu`.
`GET /api/v1/range`	—	Dataset range (first/last AD+BS), total entries, last update, seed hash.
`GET /api/v1/month`	`ad` \| `bs` (YYYY-MM)	Every day of one calendar month — powers calendar grids.
`GET /api/v1/days-since`	`ad` \| `bs`, `tz?`	Signed day count from a date to today.
`GET /api/v1/days-between`	`from_ad`\|`from_bs`, `to_ad`\|`to_bs`	Signed day count between any two dates; calendars can be mixed.
`GET /api/v1/months/:bsYear`	path: BS year	BS month lengths for a year + total days.
`GET /api/v1/dump`	—	Full database dump as a JSON attachment (meta + month table + all mappings).

Example

$ curl -s 'https://ad-bs.ajam.dev/api/v1/convert?ad=2026-07-09'
{
  "ok": true,
  "data": {
    "id": 38907,
    "ad": "2026-07-09",
    "bs": "2083-03-25",
    "day": "Thursday",
    "day_of_week": 4,
    "ad_human": "Thursday, 9th July - 2026 AD",
    "bs_human": "Thursday, 25th Ashad - 2083 BS",
    "ad_month_name": "July",
    "bs_month_name": "Ashad",
    "divergence": {
      "ad_to_bs": "+56y 8m 16d",
      "bs_to_ad": "-56y 8m 16d"
    }
  }
}

Divergence

Every entry carries a component-wise offset such that AD + ad_to_bs = BS (days borrow against real BS month lengths, months against years). The reverse direction is its exact negation. It lets you fast-forward/rewind between the calendars by whole years/months/days without re-querying.

Reliability

The dataset is a manually curated mapping of 81,919 consecutive days. Every rebuild is verified with round-trip regeneration plus a deterministic anomaly checker before it goes live, and full dumps are kept in object storage. Inputs are validated; the API returns typed errors rather than guesses.