Developer API

A small public read-only JSON API for canonical Roman numeral conversion in the standard range 1–3999. No API keys. GET only.

Endpoints

Number → Roman

GET https://roman-numerals.net/api/v1/to-roman?number=2026
{
  "number": 2026,
  "roman": "MMXXVI"
}

Roman → Number

GET https://roman-numerals.net/api/v1/from-roman?roman=MMXXVI
{
  "roman": "MMXXVI",
  "number": 2026
}

Parameters

  • number — integer from 1 to 3999
  • roman — canonical Roman numeral using I V X L C D M

Errors

Invalid input returns HTTP 400 with JSON such as:

{
  "ok": false,
  "error": "Non-standard form. The canonical Roman numeral for 4 is IV.",
  "canonicalSuggestion": "IV"
}

Out-of-range values (0, 4000), empty input, oversized strings, and non-Roman text are rejected.

Rate limits

Basic public use is rate-limited per IP (approximately 60 requests per minute). Exceeding the limit returns HTTP 429.

Notes

  • Strict canonical validation by default
  • No authentication, no write methods, no CORS wildcard
  • Attribution appreciated: link to roman-numerals.net
  • For browsers/UI embeds, prefer the iframe widget