# Scale Model API
> Scale-model maths as an API, computed locally and deterministically — the real-to-model conversions a modeller, model-railroader, wargamer or diorama-builder works in. The convert endpoint scales a dimension either way at any scale, given as a ratio (1:35), a number (87.1) or a name (Z, N, TT, HO, OO, S, O, G, 1/72, 1/48, 1/35, 1/24, 1/64, 1/43, 1/18): real → model divides by the ratio, model → real multiplies, so a 1:35 tank 6 metres long becomes 171 mm and an HO (1:87.1) boxcar 12.2 metres long becomes 140 mm, with the answer in mm, cm, m, inches and feet. The identify endpoint finds the scale from a real measurement and the model of it — scale = real ÷ model — and names the nearest standard scale with how far off it is, so you know whether figures and accessories will match. The scales endpoint lists the common named scales and compares any two, telling you that a 1:35 model is about 2.06 times the size of the same subject at 1:72. Everything is computed locally and deterministically, so it is instant and private. Ideal for scale-modelling, model-railroad, wargaming, diecast, architecture and diorama app developers, conversion and shopping tools, and hobby software. Pure local computation — no key, no third-party service, instant. Length in mm/cm/m/in/ft. Live, nothing stored. 3 compute endpoints. For typographic modular scales use a different 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/scalemodel-api/..."
```

## Pricing
- **Free** (Free) — 7,550 calls/Mo, 2 req/s
- **Starter** ($4/Mo) — 58,800 calls/Mo, 6 req/s
- **Pro** ($11/Mo) — 236,500 calls/Mo, 15 req/s
- **Mega** ($36/Mo) — 1,362,000 calls/Mo, 40 req/s

## Endpoints

### ScaleModel

#### `GET /v1/convert` — Scale convert real ↔ model

**Parameters:**
- `scale` (query, required, string) — Scale: '1:35', '87.1' or a name (HO, N, 1/72) Example: `1:35`
- `value` (query, required, string) — Dimension value Example: `6`
- `unit` (query, optional, string) — mm, cm, m, in or ft (default mm) Example: `m`
- `direction` (query, optional, string) — real_to_model or model_to_real Example: `real_to_model`

**Example:**
```bash
curl -H "x-oanor-key: $KEY" \
  "https://api.oanor.com/scalemodel-api/v1/convert?scale=1%3A35&value=6&unit=m&direction=real_to_model"
```

**Response:**
```json
{
    "data": {
        "note": "Real → model divides by the scale ratio; model → real multiplies. A 1:35 tank 6 m long is 171 mm; an HO (1:87.1) boxcar 12.2 m long is 140 mm. The scale ratio is how many real units fit in one model unit.",
        "inputs": {
            "unit": "m",
            "ratio": 35,
            "scale": "1:35",
            "value": 6,
            "direction": "real_to_model"
        },
        "result": {
            "m": 0.17143,
            "cm": 17.1429,
            "ft": 0.56243,
            "in": 6.7492,
            "mm": 171.429
        }
    },
    "meta": {
        "timestamp": "2026-06-06T07:13:59.010Z",
        "request_id": "12ee748a-2f20-4ae3-853f-7133dd263fec"
    },
    "status": "ok",
    "message": "Scale convert",
    "success": true
}
```

#### `GET /v1/identify` — Identify the scale

**Parameters:**
- `real` (query, required, string) — Real dimension Example: `1828`
- `model` (query, required, string) — Model dimension Example: `21`
- `real_unit` (query, optional, string) — Unit of real (default mm) Example: `mm`
- `model_unit` (query, optional, string) — Unit of model (default mm) Example: `mm`

**Example:**
```bash
curl -H "x-oanor-key: $KEY" \
  "https://api.oanor.com/scalemodel-api/v1/identify?real=1828&model=21&real_unit=mm&model_unit=mm"
```

**Response:**
```json
{
    "data": {
        "note": "Scale = real size ÷ model size (in the same unit). The nearest standard scale helps you buy matching figures and accessories; check the off-by percentage before mixing ranges.",
        "scale": "1:87.05",
        "inputs": {
            "real": 1828,
            "model": 21,
            "real_unit": "mm",
            "model_unit": "mm"
        },
        "scale_ratio": 87.048,
        "nearest_named_ratio": 87.1,
        "nearest_named_scale": "HO",
        "nearest_off_by_percent": 0.06
    },
    "meta": {
        "timestamp": "2026-06-06T07:13:59.112Z",
        "request_id": "bcc90878-60ff-495d-af97-c915db39eb7e"
    },
    "status": "ok",
    "message": "Identify scale",
    "success": true
}
```

#### `GET /v1/scales` — Scale reference + compare

**Parameters:**
- `scale_a` (query, optional, string) — First scale to compare Example: `1/35`
- `scale_b` (query, optional, string) — Second scale to compare Example: `1/72`

**Example:**
```bash
curl -H "x-oanor-key: $KEY" \
  "https://api.oanor.com/scalemodel-api/v1/scales?scale_a=1%2F35&scale_b=1%2F72"
```

**Response:**
```json
{
    "data": {
        "note": "Common modelling scales (real ÷ model). Smaller ratios make bigger models. Pass scale_a and scale_b to compare how much bigger one is than the other.",
        "compare": {
            "detail": "A 1:35 model is 2.057× the size of the same subject at 1:72.",
            "scale_a": "1/35",
            "scale_b": "1/72",
            "a_vs_b_size": 2.0571
        },
        "named_scales": {
            "G": "1:22.5",
            "N": "1:160",
            "O": "1:48",
            "S": "1:64",
            "Z": "1:220",
            "HO": "1:87.1",
            "OO": "1:76.1",
            "TT": "1:120",
            "1/16": "1:16",
            "1/18": "1:18",
            "1/24": "1:24",
            "1/32": "1:32",
            "1/35": "1:35",
            "1/43": "1:43",
            "1/48": "1:48",
            "1/64": "1:64",
            "1/72": "1:72",
            "1/144": "1:144"
        }
    },
    "meta": {
        "timestamp": "2026-06-06T07:13:59.216Z",
        "request_id": "f22bb882-49ef-438a-b3b2-61013b4afac8"
    },
    "status": "ok",
    "message": "Scale reference",
    "success": true
}
```

### Meta

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

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

**Response:**
```json
{
    "data": {
        "notes": "Scale ratio = real ÷ model. Accepts '1:35', a number, or names (Z, N, TT, HO, OO, S, O, G, 1/72, 1/48, 1/35, 1/24, 1/64, 1/43, 1/18). Length in mm/cm/m/in/ft. For typographic modular scales use a different API.",
        "service": "scalemodel-api",
        "endpoints": {
            "GET /v1/meta": "This document.",
            "GET /v1/scales": "Reference of common named scales and a two-scale size comparison.",
            "GET /v1/convert": "Convert a real or model dimension at a scale (ratio or named).",
            "GET /v1/identify": "Find the scale from a real and a model measurement."
        },
        "description": "Scale-model maths: real ↔ model dimension conversion, scale identification, and a reference of common named scales."
    },
    "meta": {
        "timestamp": "2026-06-06T07:13:59.313Z",
        "request_id": "e3bed144-737f-471c-bafe-9e6e961eb43f"
    },
    "status": "ok",
    "message": "Meta",
    "success": true
}
```


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