Free Roman Numeral JSON API

Endpoint

GET https://romannumerals.app/api/roman/{number}
GET https://romannumerals.app/api/roman/{number}.json

Example

Request the numeral for 47:

curl https://romannumerals.app/api/roman/47

Response:

{
  "ok": true,
  "number": 47,
  "roman": "XLVII",
  "spelled": "forty-seven",
  "breakdown": [
    { "glyph": "XL", "value": 40 },
    { "glyph": "V", "value": 5 },
    { "glyph": "I", "value": 1 },
    { "glyph": "I", "value": 1 }
  ],
  "source": "https://romannumerals.app/numbers/47-in-roman-numerals"
}

Use it in your language

The endpoint is plain HTTPS returning JSON, so every language's standard tooling works without a client library.

JavaScript

const res = await fetch("https://romannumerals.app/api/roman/2025");
const data = await res.json();
console.log(data.roman); // "MMXXV"

Python

import urllib.request, json

with urllib.request.urlopen("https://romannumerals.app/api/roman/2025") as r:
    data = json.load(r)
print(data["roman"])  # MMXXV

PHP

$data = json_decode(file_get_contents("https://romannumerals.app/api/roman/2025"), true);
echo $data["roman"]; // MMXXV

Ruby

require "net/http"
require "json"

data = JSON.parse(Net::HTTP.get(URI("https://romannumerals.app/api/roman/2025")))
puts data["roman"] # MMXXV

Go

res, _ := http.Get("https://romannumerals.app/api/roman/2025")
defer res.Body.Close()
var data struct{ Roman string `json:"roman"` }
json.NewDecoder(res.Body).Decode(&data)
fmt.Println(data.Roman) // MMXXV

curl

curl -s https://romannumerals.app/api/roman/2025 | jq .roman

Fields

number: the input value as an integer.
roman: the standard Roman numeral, for example XLVII.
spelled: the English words, for example forty-seven.
breakdown: the additive parts, each a glyph and its value.
source: a link to the full reference page for that number.

Errors

A number below 1 or above 3999, or a non-integer, returns HTTP 400 with { "ok": false, "error": "..." }. Everything else returns HTTP 200.

Rate limits and reliability

There is no rate limit and no key. Responses are static and served from a CDN, so the endpoint is fast and safe to call from client-side code, build scripts and classroom projects alike. If you expect sustained heavy traffic (millions of calls), the same data can simply be computed locally; the conversion algorithm is standard, and the endpoint exists for convenience, not lock-in.

A link back to Numerus is appreciated but not required. If the API helps your project, a credit to romannumerals.app helps others find it.

Frequently asked questions

Is the Roman numeral API free?

Yes. It is a free static endpoint with no key, no rate limit and permissive CORS, so you can call it from the browser or a server.

What range does the API cover?

Every integer from 1 to 3999, the standard Roman numeral range. Values outside that return a 400 with a clear message.

Prefer a widget?

If you want a visible converter on your own site rather than raw JSON, embed the Numerus converter widget with a single snippet.