# Number API
> A fast, fully-local number toolkit: spell numbers out in English words (great for amount-in-words on invoices and cheques), format ordinals (1st, 2nd, 112th), convert integers to and from Roman numerals (1 to 3999), convert numbers between any bases from 2 to 36, and format numbers locale-aware as decimal, currency or percent. Every endpoint accepts input via the query string or the request body. Pure server-side compute, no third-party upstream, so responses are instant and always available. Ideal for invoicing and billing, localization, education and developer formatting tooling.

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

## Pricing
- **Free** (Free) — 17,000 calls/Mo, 2 req/s
- **Basic** ($4/Mo) — 270,000 calls/Mo, 12 req/s
- **Pro** ($12/Mo) — 1,600,000 calls/Mo, 40 req/s
- **Mega** ($32/Mo) — 8,500,000 calls/Mo, 150 req/s

## Endpoints

### Number

#### `GET /v1/base` — Base conversion (2-36)

**Parameters:**
- `number` (query, required, string) — Number in the source base Example: `ff`
- `from` (query, optional, string) — Source base (default 10) Example: `16`
- `to` (query, optional, string) — Target base (default 10) Example: `2`

**Example:**
```bash
curl -H "x-oanor-key: $KEY" \
  "https://api.oanor.com/number-api/v1/base?number=ff&from=16&to=2"
```

**Response:**
```json
{
    "data": {
        "to": 2,
        "from": 16,
        "input": "ff",
        "value": 255,
        "result": "11111111"
    },
    "meta": {
        "timestamp": "2026-05-30T10:10:55.975Z",
        "request_id": "5c8125db-c4c8-4d18-b0a1-5678bee5cbab"
    },
    "status": "ok",
    "message": "OK",
    "success": true
}
```

#### `GET /v1/format` — Locale number formatting

**Parameters:**
- `number` (query, required, string) — Number Example: `1234567.89`
- `locale` (query, optional, string) — BCP-47 locale (default en-US) Example: `de-DE`
- `style` (query, optional, string) — decimal, currency or percent Example: `currency`
- `currency` (query, optional, string) — ISO 4217 code (for currency) Example: `EUR`

**Example:**
```bash
curl -H "x-oanor-key: $KEY" \
  "https://api.oanor.com/number-api/v1/format?number=1234567.89&locale=de-DE&style=currency&currency=EUR"
```

**Response:**
```json
{
    "data": {
        "style": "currency",
        "locale": "de-DE",
        "number": 1234567.89,
        "formatted": "1.234.567,89 €"
    },
    "meta": {
        "timestamp": "2026-05-30T10:10:56.053Z",
        "request_id": "07deeeab-cb92-4901-a50f-ea6b000aaa16"
    },
    "status": "ok",
    "message": "OK",
    "success": true
}
```

#### `GET /v1/ordinal` — Ordinal form

**Parameters:**
- `number` (query, required, string) — Integer Example: `112`

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

**Response:**
```json
{
    "data": {
        "number": 112,
        "ordinal": "112th",
        "ordinal_words": "one hundred twelve"
    },
    "meta": {
        "timestamp": "2026-05-30T10:10:56.137Z",
        "request_id": "b24e2592-f79d-4190-b0ba-afc8df358e37"
    },
    "status": "ok",
    "message": "OK",
    "success": true
}
```

#### `GET /v1/roman` — Roman numeral conversion

**Parameters:**
- `value` (query, optional, string) — Integer 1-3999 (value to roman) Example: `1994`
- `roman` (query, optional, string) — Roman numeral (roman to value) Example: `MCMXCIV`

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

**Response:**
```json
{
    "data": {
        "roman": "MCMXCIV",
        "value": 1994
    },
    "meta": {
        "timestamp": "2026-05-30T10:10:56.211Z",
        "request_id": "cf02fba5-7d14-4fd6-b34c-a791e4a87d09"
    },
    "status": "ok",
    "message": "OK",
    "success": true
}
```

#### `GET /v1/words` — Number to English words

**Parameters:**
- `number` (query, required, string) — Integer Example: `1234567`

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

**Response:**
```json
{
    "data": {
        "words": "one million two hundred thirty-four thousand five hundred sixty-seven",
        "number": "1234567"
    },
    "meta": {
        "timestamp": "2026-05-30T10:10:56.279Z",
        "request_id": "96783902-62b2-405c-a227-042a8319cb50"
    },
    "status": "ok",
    "message": "OK",
    "success": true
}
```


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