# Roman Numeral API
> Roman numeral conversion as an API, computed locally and deterministically. The encode endpoint turns an integer from 1 to 3999 into its Roman numeral using standard subtractive notation, so 1994 becomes MCMXCIV and 2024 becomes MMXXIV. The decode endpoint turns a Roman numeral back into an integer with strict validation — it rejects malformed forms such as IIII or VV and also returns the canonical way to write the same value, accepting any letter case. The arithmetic endpoint adds, subtracts or multiplies two values given as either integers or Roman numerals and returns the result as a Roman numeral and as an integer, provided the result stays within the classic 1–3999 range. The standard subtractive pairs are IV, IX, XL, XC, CD and CM. Everything is computed locally and deterministically, so it is instant and private. Ideal for typesetting, publishing, education, clock-face, game and document-processing app developers, numbering and chapter tools, and history teaching. Pure local computation — no key, no third-party service, instant. Live, nothing stored. 3 endpoints. This is Roman numeral conversion; for binary, octal and hexadecimal number-base conversion use a base-conversion API.

## Authentication
All requests require your oanor API key in the `x-oanor-key` header. Get one at https://www.oanor.com/developer/keys.

```bash
curl -H "x-oanor-key: oanor_live_…" "https://api.oanor.com/roman-api/..."
```

## Pricing
- **Free** (Free) — 5,000 calls/Mo, 2 req/s
- **Starter** ($5/Mo) — 47,000 calls/Mo, 6 req/s
- **Pro** ($13/Mo) — 225,000 calls/Mo, 15 req/s
- **Mega** ($41/Mo) — 1,320,000 calls/Mo, 40 req/s

## Endpoints

### Roman

#### `GET /v1/arithmetic` — Roman arithmetic

**Parameters:**
- `a` (query, required, string) — First operand (integer or Roman) Example: `XIV`
- `b` (query, required, string) — Second operand (integer or Roman) Example: `VI`
- `operation` (query, optional, string) — add, subtract or multiply Example: `add`

**Example:**
```bash
curl -H "x-oanor-key: $KEY" \
  "https://api.oanor.com/roman-api/v1/arithmetic?a=XIV&b=VI&operation=add"
```

**Response:**
```json
{
    "data": {
        "note": "Operands may be given as integers or Roman numerals. The result must stay within 1–3999 to be expressible in standard Roman notation.",
        "inputs": {
            "a": 14,
            "b": 6,
            "operation": "add"
        },
        "result_roman": "XX",
        "result_value": 20,
        "operands_roman": {
            "a": "XIV",
            "b": "VI"
        }
    },
    "meta": {
        "timestamp": "2026-06-05T11:30:34.630Z",
        "request_id": "df39ed36-664a-43c3-8d4e-e0d4d78f2e34"
    },
    "status": "ok",
    "message": "Roman arithmetic",
    "success": true
}
```

#### `GET /v1/decode` — Roman to integer

**Parameters:**
- `roman` (query, required, string) — Roman numeral Example: `MCMXCIV`

**Example:**
```bash
curl -H "x-oanor-key: $KEY" \
  "https://api.oanor.com/roman-api/v1/decode?roman=MCMXCIV"
```

**Response:**
```json
{
    "data": {
        "note": "Decoded with strict validation (rejects forms like IIII or VV). The canonical form is the standard way to write the same value.",
        "value": 1994,
        "inputs": {
            "roman": "MCMXCIV"
        },
        "canonical": "MCMXCIV"
    },
    "meta": {
        "timestamp": "2026-06-05T11:30:34.765Z",
        "request_id": "6f73852a-7d5e-44f7-b907-7f6b87fc42f4"
    },
    "status": "ok",
    "message": "Roman to integer",
    "success": true
}
```

#### `GET /v1/encode` — Integer to Roman

**Parameters:**
- `number` (query, required, string) — Integer 1–3999 Example: `1994`

**Example:**
```bash
curl -H "x-oanor-key: $KEY" \
  "https://api.oanor.com/roman-api/v1/encode?number=1994"
```

**Response:**
```json
{
    "data": {
        "note": "Standard subtractive Roman notation for 1–3999 (e.g. 1994 → MCMXCIV). Values above 3999 need a vinculum (overline) which is outside the classic range.",
        "roman": "MCMXCIV",
        "inputs": {
            "number": 1994
        }
    },
    "meta": {
        "timestamp": "2026-06-05T11:30:34.844Z",
        "request_id": "4b2f355a-66bb-42f2-90c3-75c376be0c85"
    },
    "status": "ok",
    "message": "Integer to Roman",
    "success": true
}
```

### Meta

#### `GET /v1/meta` — Spec

**Example:**
```bash
curl -H "x-oanor-key: $KEY" \
  "https://api.oanor.com/roman-api/v1/meta"
```

**Response:**
```json
{
    "data": {
        "notes": "Classic range 1–3999 with standard subtractive notation (IV, IX, XL, XC, CD, CM). Decode rejects non-canonical forms like IIII or VV.",
        "service": "roman-api",
        "endpoints": {
            "GET /v1/meta": "This document.",
            "GET /v1/decode": "Roman numeral to an integer, with validation and canonical form.",
            "GET /v1/encode": "Integer (1–3999) to a Roman numeral.",
            "GET /v1/arithmetic": "Add, subtract or multiply two Roman numerals or integers, result in Roman."
        },
        "description": "Roman numeral converter: encode an integer to a Roman numeral, decode a Roman numeral to an integer with strict validation, and do arithmetic (add, subtract, multiply) on Roman numerals."
    },
    "meta": {
        "timestamp": "2026-06-05T11:30:34.938Z",
        "request_id": "848396cb-fc32-4e1f-b932-4b45dad2966d"
    },
    "status": "ok",
    "message": "Meta",
    "success": true
}
```


---
Marketplace page: https://www.oanor.com/api/roman-api
OpenAPI spec: https://www.oanor.com/api/roman-api/openapi.json