# Number Words API
> Format numbers in human-readable forms as an API. Spell any number in English words — handling thousands through quintillions, negatives and decimals (e.g. 1,234,567 → "one million two hundred thirty-four thousand five hundred sixty-seven", 12.56 → "twelve point five six"). Turn a whole number into its ordinal, both short (21 → 21st, 113 → 113th) and written out (twenty-first, one hundred thirteenth). And convert any whole number from 1 to 3999 to Roman numerals and back (2024 ⇄ MMXXIV), with strict validation. Everything runs locally, so it is fast and always available. Ideal for invoices, cheques and accounting, legal documents, internationalisation, accessibility (screen readers), education and any UI that turns digits into words.

## 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/numberwords-api/..."
```

## Pricing
- **Free** (Free) — 14,500 calls/Mo, 2 req/s
- **Starter** ($2/Mo) — 225,000 calls/Mo, 8 req/s
- **Pro** ($8/Mo) — 880,000 calls/Mo, 20 req/s
- **Mega** ($27/Mo) — 3,600,000 calls/Mo, 50 req/s

## Endpoints

### Numbers

#### `GET /v1/ordinal` — Ordinal of a whole number (short + words)

**Parameters:**
- `number` (query, required, string) — A whole number, e.g. 21 Example: `21`

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

**Response:**
```json
{
    "data": {
        "number": 21,
        "ordinal": "21st",
        "ordinal_words": "twenty-first"
    },
    "meta": {
        "timestamp": "2026-06-01T00:04:26.211Z",
        "request_id": "f544ffd4-25e8-448e-97a1-52a8720188ff"
    },
    "status": "ok",
    "message": "Ordinal formatted",
    "success": true
}
```

#### `GET /v1/roman` — Whole number ↔ Roman numeral (1-3999)

**Parameters:**
- `number` (query, optional, string) — A number 1-3999 to convert to Roman, e.g. 2024 Example: `2024`
- `roman` (query, optional, string) — A Roman numeral to convert to a number, e.g. MMXXIV

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

**Response:**
```json
{
    "data": {
        "roman": "MMXXIV",
        "number": 2024
    },
    "meta": {
        "timestamp": "2026-06-01T00:04:26.283Z",
        "request_id": "6de29eb1-44f5-4e74-a97f-e4ce2cf49f2e"
    },
    "status": "ok",
    "message": "Roman numeral converted",
    "success": true
}
```

#### `GET /v1/words` — Spell a number in English words

**Parameters:**
- `number` (query, required, string) — A number (negatives & decimals ok), e.g. 1234 Example: `1234`

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

**Response:**
```json
{
    "data": {
        "words": "one thousand two hundred thirty-four",
        "number": "1234"
    },
    "meta": {
        "timestamp": "2026-06-01T00:04:26.329Z",
        "request_id": "d79f90f2-35bb-4068-a592-a8720d48a08e"
    },
    "status": "ok",
    "message": "Number spelled",
    "success": true
}
```

### Meta

#### `GET /v1/meta` — Usage notes

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

**Response:**
```json
{
    "data": {
        "note": "Number formatting. /v1/words = spell a number in English words (e.g. 1234 → one thousand two hundred thirty-four; handles negatives and decimals via 'point'); /v1/ordinal = the ordinal of a whole number, short (21 → 21st) and in words (twenty-first); /v1/roman = a whole number 1-3999 to Roman numerals (number=2024 → MMXXIV) or back (roman=MMXXIV → 2024). Runs fully locally.",
        "source": "local number-formatting engine",
        "endpoints": [
            "/v1/words",
            "/v1/ordinal",
            "/v1/roman",
            "/v1/meta"
        ]
    },
    "meta": {
        "timestamp": "2026-06-01T00:04:26.395Z",
        "request_id": "835a6cb5-f72c-48e9-b32b-dceec6e31e28"
    },
    "status": "ok",
    "message": "Meta retrieved",
    "success": true
}
```


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