# Viewing Distance API
> TV and projector viewing-distance maths as an API, computed locally and deterministically. The distance endpoint takes a screen diagonal (inches or centimetres) and aspect ratio and returns the screen width and height and the recommended seating distance for each standard — SMPTE's 30° minimum viewing angle (the farthest comfortable seat), THX's 36° recommendation and THX's 40° maximum (the closest) — in inches, feet, centimetres and metres, plus an overall recommended range. Pass a resolution (720p, 1080p, 1440p, 4K or 8K) and it also gives the pixel-acuity distance, the point beyond which a 20/20 viewer can no longer resolve individual pixels, so moving closer stops adding detail. The screensize endpoint reverses it: from a seating distance it recommends the screen diagonal for each standard. The fov endpoint gives the horizontal field of view for a screen at a distance, with a verdict on whether it falls in the recommended range. The geometry is exact: width = diagonal × aspect-width / hypot(aspect), and distance = (width/2) / tan(angle/2). Everything is computed locally and deterministically, so it is instant and private. Ideal for home-theatre and AV apps, TV and monitor retail tools, room and seating planners, and AV-installer calculators. Pure local computation — no key, no third-party service, instant. Live, nothing stored. 3 endpoints. This is viewing-distance geometry; for pixel density (PPI) from a resolution use a PPI 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/viewdistance-api/..."
```

## Pricing
- **Free** (Free) — 13,235 calls/Mo, 2 req/s
- **Starter** ($15/Mo) — 22,850 calls/Mo, 8 req/s
- **Pro** ($35/Mo) — 278,500 calls/Mo, 20 req/s
- **Mega** ($73/Mo) — 1,435,000 calls/Mo, 50 req/s

## Endpoints

### View

#### `GET /v1/distance` — Viewing distance from screen size

**Parameters:**
- `diagonal` (query, required, string) — Screen diagonal Example: `65`
- `unit` (query, optional, string) — in|cm|m (default in) Example: `in`
- `aspect` (query, optional, string) — Aspect ratio (default 16:9) Example: `16:9`
- `resolution` (query, optional, string) — 720p|1080p|1440p|4k|8k (for pixel acuity) Example: `4k`

**Example:**
```bash
curl -H "x-oanor-key: $KEY" \
  "https://api.oanor.com/viewdistance-api/v1/distance?diagonal=65&unit=in&aspect=16%3A9&resolution=4k"
```

**Response:**
```json
{
    "data": {
        "note": "Distance D = (width/2) / tan(angle/2). SMPTE 30° = farthest comfortable; THX 40° = closest. Wider angle = more immersive but needs higher resolution.",
        "resolution": {
            "label": "4k",
            "vertical_pixels": 2160
        },
        "aspect_ratio": "16:9",
        "screen_width": {
            "cm": 143.9,
            "feet": 4.72,
            "inches": 56.7,
            "metres": 1.44
        },
        "screen_height": {
            "cm": 80.9,
            "feet": 2.66,
            "inches": 31.9,
            "metres": 0.81
        },
        "diagonal_inches": 65,
        "recommendations": {
            "thx_36deg": {
                "cm": 221.4,
                "feet": 7.26,
                "inches": 87.2,
                "metres": 2.21
            },
            "smpte_30deg": {
                "cm": 268.5,
                "feet": 8.81,
                "inches": 105.7,
                "metres": 2.69
            },
            "thx_40deg_max": {
                "cm": 197.7,
                "feet": 6.49,
                "inches": 77.8,
                "metres": 1.98
            }
        },
        "pixel_acuity_note": "At or beyond this distance a 20/20 viewer can no longer resolve individual pixels — moving closer stops adding detail.",
        "recommended_range": {
            "closest": {
                "cm": 197.7,
                "feet": 6.49,
                "inches": 77.8,
                "metres": 1.
…(truncated, see openapi.json for full schema)
```

#### `GET /v1/fov` — Field of view from distance & size

**Parameters:**
- `diagonal` (query, required, string) — Screen diagonal Example: `65`
- `unit` (query, optional, string) — Diagonal unit in|cm|m Example: `in`
- `distance` (query, required, string) — Seating distance Example: `105`
- `distance_unit` (query, optional, string) — in|cm|m|ft Example: `in`
- `aspect` (query, optional, string) — Aspect ratio Example: `16:9`

**Example:**
```bash
curl -H "x-oanor-key: $KEY" \
  "https://api.oanor.com/viewdistance-api/v1/fov?diagonal=65&unit=in&distance=105&distance_unit=in&aspect=16%3A9"
```

**Response:**
```json
{
    "data": {
        "note": "Horizontal field of view = 2 · atan(width / (2 · distance)). SMPTE recommends ≥30°, THX 36–40°.",
        "assessment": "Within the SMPTE–THX recommended range.",
        "aspect_ratio": "16:9",
        "diagonal_inches": 65,
        "distance_inches": 105,
        "horizontal_fov_degrees": 30.2
    },
    "meta": {
        "timestamp": "2026-06-04T01:59:10.542Z",
        "request_id": "52228841-62da-466d-a842-38c149c2619b"
    },
    "status": "ok",
    "message": "Field of view from distance and screen size",
    "success": true
}
```

#### `GET /v1/screensize` — Screen size from seating distance

**Parameters:**
- `distance` (query, required, string) — Seating distance Example: `105`
- `unit` (query, optional, string) — in|cm|m|ft (default in) Example: `in`
- `aspect` (query, optional, string) — Aspect ratio (default 16:9) Example: `16:9`

**Example:**
```bash
curl -H "x-oanor-key: $KEY" \
  "https://api.oanor.com/viewdistance-api/v1/screensize?distance=105&unit=in&aspect=16%3A9"
```

**Response:**
```json
{
    "data": {
        "note": "Recommended screen diagonal for this seating distance. SMPTE 30° gives the smallest, THX 40° the largest (most immersive).",
        "distance": {
            "cm": 266.7,
            "feet": 8.75,
            "inches": 105,
            "metres": 2.67
        },
        "aspect_ratio": "16:9",
        "recommended_range": {
            "largest": {
                "cm": 222.7,
                "feet": 7.31,
                "inches": 87.7,
                "metres": 2.23
            },
            "smallest": {
                "cm": 164,
                "feet": 5.38,
                "inches": 64.6,
                "metres": 1.64
            }
        },
        "recommended_diagonal": {
            "thx_36deg": {
                "cm": 198.8,
                "feet": 6.52,
                "inches": 78.3,
                "metres": 1.99
            },
            "smpte_30deg": {
                "cm": 164,
                "feet": 5.38,
                "inches": 64.6,
                "metres": 1.64
            },
            "thx_40deg_max": {
                "cm": 222.7,
                "feet": 7.31,
                "inches": 87.7,
                "metres": 2.23
            }
        }
    },
    "meta": {
        "timestamp": "2026-06-04T01:59:10.626Z",
        "request_id": "9a867460-b691-488e-8c59-fc1f6fca2cfe"
    },
    "status": "ok",
    "message": "Recommended screen size from seating distance",
    "success": true
}
```

### Meta

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

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

**Response:**
```json
{
    "data": {
        "api": "viewdistance",
        "note": "TV/projector viewing-distance maths — computed locally and deterministically, no key, no third-party service.",
        "endpoints": [
            "/v1/distance",
            "/v1/screensize",
            "/v1/fov",
            "/v1/meta"
        ],
        "standards": {
            "smpte": 30,
            "thx_max": 40,
            "thx_rec": 36
        },
        "resolutions": [
            "480p",
            "720p",
            "1080p",
            "1440p",
            "4k",
            "2160p",
            "8k",
            "4320p"
        ]
    },
    "meta": {
        "timestamp": "2026-06-04T01:59:10.705Z",
        "request_id": "d12fc409-ce60-4013-990a-64b58a3b314e"
    },
    "status": "ok",
    "message": "Meta",
    "success": true
}
```


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