API

· Overview ·

A read-only API for roman numerals. All endpoints return JSON and allow CORS from any origin. Static responses (everything except /today) are CDN-cached for a week; /today is cached until the next midnight in Europe/Stockholm. Browsers always revalidate (max-age=0).

The valid range is 1–3999, which is what classical roman numerals can express.

• GET /api/v1/to/{n}

  Convert an arabic number (1–3999) to a roman numeral.

  https://roman.tammergard.se/api/v1/to/2026

• GET /api/v1/from/{roman}

  Convert a roman numeral to an arabic number.

  https://roman.tammergard.se/api/v1/from/MMXXVI

• GET /api/v1/validate/{roman}

  Check whether a string is a well-formed roman numeral (1–3999).

  https://roman.tammergard.se/api/v1/validate/MMXXVI

• GET /api/v1/convert/{value}

  Convert in either direction automatically. Accepts either an arabic number or a roman numeral.

  https://roman.tammergard.se/api/v1/convert/MMXXVI

• GET /api/v1/today

  Today's date (Europe/Stockholm) as roman numerals, with the Latin month name.

  https://roman.tammergard.se/api/v1/today

• GET /api/v1/all

  All numerals from 1 to 3999 as arabic/roman pairs. The response is around 100 KB.

  https://roman.tammergard.se/api/v1/all

/to/{n} and /from/{roman} return a pair:

{
  "arabic": 2026,
  "roman": "MMXXVI"
}

/convert/{value} additionally includes a kind field that shows which direction it converted:

{
  "kind": "roman",
  "input": "MMXXVI",
  "roman": "MMXXVI",
  "arabic": 2026
}

Errors are returned as JSON. Status codes:

• 400 – missing or malformed parameter (e.g. empty string, invalid characters).
• 422 – well-formed input but invalid value (e.g. /to/5000 or /from/IIII).

{
  "error": {
    "status": 422,
    "message": "Invalid number \"5000\". Must be between 1 and 3999."
  }
}

This API is built on the @tammergard/roman package on npm.