# Number Representations API
> Convert integers and numbers into the special number representations that ordinary base conversion leaves out — and back again. The graycode endpoint converts between an integer and its reflected binary Gray code, where consecutive values differ by exactly one bit (used in rotary encoders, Karnaugh maps and error reduction). The balanced-ternary endpoint converts between an integer and balanced ternary, the base-3 system with digits −1, 0 and +1 (written T, 0, 1) that needs no separate sign. The factoradic endpoint converts between an integer and the factorial number system (mixed radix 1, 2, 3, …), the basis of permutation ranking and Lehmer codes. The continued-fraction endpoint turns a fraction or a real number into its continued-fraction expansion [a0; a1, a2, …] and lists the convergents — the successively best rational approximations — and can rebuild the value from the terms. All integer maths is exact via big integers. Everything is computed locally and deterministically, so it is instant and private. Ideal for computer-science teaching, combinatorics and permutation ranking, error-correcting and encoder design, rational approximation, and recreational mathematics. Pure local computation — no key, no third-party service, instant. Live, nothing stored. 5 endpoints. This handles special number representations; for ordinary base 2-36 conversion use a base-convert 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/numrep-api/..."
```

## Pricing
- **Free** (Free) — 6,335 calls/Mo, 2 req/s
- **Starter** ($8/Mo) — 15,850 calls/Mo, 8 req/s
- **Pro** ($28/Mo) — 209,500 calls/Mo, 20 req/s
- **Mega** ($66/Mo) — 1,090,000 calls/Mo, 50 req/s

## Endpoints

### Numbers

#### `GET /v1/balanced-ternary` — Balanced ternary

**Parameters:**
- `n` (query, optional, string) — Integer to encode Example: `5`
- `bt` (query, optional, string) — Or balanced-ternary (1,0,T) to decode

**Example:**
```bash
curl -H "x-oanor-key: $KEY" \
  "https://api.oanor.com/numrep-api/v1/balanced-ternary?n=5"
```

**Response:**
```json
{
    "data": {
        "input": {
            "n": "5"
        },
        "decimal": "5",
        "digits_note": "T means -1",
        "balanced_ternary": "1TT"
    },
    "meta": {
        "timestamp": "2026-06-03T17:42:13.746Z",
        "request_id": "3c3bb68f-dc1d-4f66-bf7a-739d2be69e7c"
    },
    "status": "ok",
    "message": "Balanced ternary",
    "success": true
}
```

#### `GET /v1/continued-fraction` — Continued fraction

**Parameters:**
- `fraction` (query, optional, string) — p/q Example: `415/93`
- `value` (query, optional, string) — Or a real number
- `terms` (query, optional, string) — Or [a0,a1,...] to rebuild

**Example:**
```bash
curl -H "x-oanor-key: $KEY" \
  "https://api.oanor.com/numrep-api/v1/continued-fraction?fraction=415%2F93"
```

**Response:**
```json
{
    "data": {
        "input": {
            "numerator": "415",
            "denominator": "93"
        },
        "terms": [
            4,
            2,
            6,
            7
        ],
        "reduced": "415/93",
        "convergents": [
            {
                "den": "1",
                "num": "4",
                "value": 4
            },
            {
                "den": "2",
                "num": "9",
                "value": 4.5
            },
            {
                "den": "13",
                "num": "58",
                "value": 4.461538461538462
            },
            {
                "den": "93",
                "num": "415",
                "value": 4.462365591397849
            }
        ]
    },
    "meta": {
        "timestamp": "2026-06-03T17:42:13.839Z",
        "request_id": "1dee780e-b335-40e9-8260-8612b99c8ba3"
    },
    "status": "ok",
    "message": "Continued fraction",
    "success": true
}
```

#### `GET /v1/factoradic` — Factorial base

**Parameters:**
- `n` (query, optional, string) — Integer to encode Example: `463`
- `factoradic` (query, optional, string) — Or factoradic digits to decode

**Example:**
```bash
curl -H "x-oanor-key: $KEY" \
  "https://api.oanor.com/numrep-api/v1/factoradic?n=463"
```

**Response:**
```json
{
    "data": {
        "note": "rightmost digit is the 0!-place (always 0)",
        "input": {
            "n": "463"
        },
        "decimal": "463",
        "factoradic": "341010"
    },
    "meta": {
        "timestamp": "2026-06-03T17:42:13.948Z",
        "request_id": "e6c66dae-56ad-4571-83e0-04314e06d577"
    },
    "status": "ok",
    "message": "Factoradic",
    "success": true
}
```

#### `GET /v1/graycode` — Gray code encode/decode

**Parameters:**
- `n` (query, optional, string) — Integer to encode Example: `5`
- `gray` (query, optional, string) — Or Gray-code binary to decode

**Example:**
```bash
curl -H "x-oanor-key: $KEY" \
  "https://api.oanor.com/numrep-api/v1/graycode?n=5"
```

**Response:**
```json
{
    "data": {
        "input": {
            "n": "5"
        },
        "binary": "101",
        "decimal": "5",
        "gray_code": "111"
    },
    "meta": {
        "timestamp": "2026-06-03T17:42:14.042Z",
        "request_id": "0b3eabfe-301e-44bd-a2a8-9772d02e6601"
    },
    "status": "ok",
    "message": "Gray code",
    "success": true
}
```

### Meta

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

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

**Response:**
```json
{
    "data": {
        "name": "Number Representations API",
        "notes": "Gray/balanced-ternary/factoradic are exact via big integers. A real value's continued fraction is approximate with a bounded number of terms. Nothing is stored.",
        "version": "v1",
        "endpoints": [
            {
                "path": "/v1/graycode",
                "params": {
                    "n": "a non-negative integer to encode",
                    "gray": "or a Gray-code binary string to decode"
                },
                "returns": "the Gray code and the plain binary/decimal"
            },
            {
                "path": "/v1/balanced-ternary",
                "params": {
                    "n": "an integer to encode",
                    "bt": "or a balanced-ternary string (1,0,T) to decode"
                },
                "returns": "the balanced-ternary form (T = -1)"
            },
            {
                "path": "/v1/factoradic",
                "params": {
                    "n": "a non-negative integer to encode",
                    "factoradic": "or a factoradic digit string to decode"
                },
                "returns": "the factorial-base form"
            },
            {
                "path": "/v1/continued-fraction",
                "params": {
                    "terms": "[a0,a1,...] to rebuild",
                    "value": "a real number",
                    "fraction": "p/q",
                    "numerator": "& deno
…(truncated, see openapi.json for full schema)
```


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