Roman Numeral Math API

About the Roman Numeral Math API

Roman Numeral Math lets you add, subtract, multiply and divide Roman numerals without writing the conversion yourself. Send two numerals and an operation and get back the answer as a Roman numeral and as a number, plus the full equation written both ways, such as XIV + IX = XXIII next to 14 + 9 = 23.

It suits Roman arithmetic exercises in education apps, history and puzzle games, clock and date features that display Roman numerals, and anyone who wants to calculate Roman numerals or add Roman numerals from a spreadsheet or script. Both inputs are checked for proper form first, so a malformed numeral is reported instead of being guessed at.

Everything is available on the Free plan. Each response echoes the two numerals, their numeric values and the operation applied, so the result can be shown with its working. Answers are limited to the range standard Roman numerals can express, and a result outside it returns an explanation rather than an invented numeral.

How it works

roman1 and roman2 are uppercased and then validated against the canonical pattern for numerals from I to MMMCMXCIX: no symbol repeated more than three times in a row and only the six standard subtractive pairs (IV, IX, XL, XC, CD, CM). Forms such as IIII, IC or VV fail with a 400 that names the bad numeral, so both operands are always between 1 and 3999. Each is converted to an integer by a left-to-right scan that subtracts a smaller symbol placed before a larger one.

operation is one of add (the default), subtract, multiply or divide, case-insensitive. Division is integer division rounded down and the remainder is discarded, so XX divided by III returns VI. The integer result is then converted back greedily from the largest value down.

Roman numerals have no zero, no negatives and, in standard form, nothing above 3999. A subtraction that comes to zero or less, or a product or sum above 3999, returns a 400 with a message explaining which limit was hit, rather than a partial result.

On success, result_number and result_roman hold the answer. equation_numeric and equation_roman write out the whole calculation with the operators +, -, × and ÷, using the numerals as you sent them after uppercasing. roman1_value and roman2_value are the parsed operands, which is a convenient way to show a learner what each numeral means.

What people use it for

Educational Tools

Teach Roman numeral arithmetic and ancient mathematics in interactive learning applications

Historical Calculators

Create calculators for historical contexts requiring Roman numeral operations

Puzzle Games

Build mathematical puzzles and games using Roman numeral arithmetic

Format Conversion

Perform calculations while maintaining Roman numeral formatting for specialized applications

Ways to call it

One endpoint, many ways in — REST with JSON, XML, YAML and CSV, plus GraphQL and an MCP interface for AI agents.

JSON

Default REST response

XML

Markup format

YAML

Human-readable

CSV

Tabular export

Beta

GraphQL

Query language

New

MCP

For AI agents

Request parameters — GET /v1/romannumeralmath

Sent in the query string. Premium parameters are accepted on every plan but only take effect on plans that include them. Anything not listed here is dropped rather than passed through.

Required

Optional

1
2

curl "https://api.apiverve.com/v1/romannumeralmath?roman1=XIV&roman2=VI&operation=add" \
  -H "x-api-key: YOUR_API_KEY"

Authentication

Send your key in the x-api-key header. That is the only auth step — no token exchange, and no per-endpoint scope to configure.

Response — GET /v1/romannumeralmath

Every APIVerve endpoint returns the same three top-level keys, so one response handler covers your whole integration: status, error and data. Only data changes shape.

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15

{
  "status": "ok",
  "error": null,
  "data": {
    "roman1": "XIV",
    "roman2": "VI",
    "roman1_value": 14,
    "roman2_value": 6,
    "operation": "add",
    "result_number": 20,
    "result_roman": "XX",
    "equation_numeric": "14 + 6 = 20",
    "equation_roman": "XIV + VI = XX"
  }
}

Response fields

Paths are relative to data. Premium fields are absent rather than zeroed on plans that do not include them, so check for presence instead of comparing to 0.

Response headers

Every response carries your balance, so your own code always knows where it stands without polling anything. All four are exposed to browsers through CORS.

Errors

Read the HTTP status first, then error for the specific reason. The body names the parameter that has to change.

What a call costs — 1 credits per call

Credits are shared across every APIVerve API — one balance, one key, one bill. Failed requests never count against it, so a rejected input costs nothing.

Calls are what the credits buy at this API's rate — spend them here, on any of the other APIs, or across both. Nothing is reserved per endpoint.

Zero-code embed — one snippet, no backend

Drop an interactive Roman Numeral Math form onto any page. The widget calls the API for you, so no key ever appears in your markup and there is nothing to deploy.

Changelog — Roman Numeral Math API

Every change to this endpoint, newest first. Breaking changes ship as a new version and the previous one keeps serving — response fields are added, never removed or retyped in place, so an integration written against v1 keeps working.

Currently v1