# Telescope Optics API
> Telescope optics maths as an API, computed locally and deterministically — the magnification, exit-pupil and resolving-power numbers an amateur astronomer or stargazing-app developer picks gear and eyepieces with. The magnification endpoint gives magnification = the telescope's focal length ÷ the eyepiece focal length (a 1000 mm scope with a 10 mm eyepiece is 100×), the focal ratio, and — from the aperture — the useful range from about the aperture in mm ÷ 7 (lowest useful, a 7 mm exit pupil) up to roughly 2× the aperture in mm, beyond which the image only dims and blurs; pass an eyepiece apparent field and it returns the true field of view. The exit-pupil endpoint gives aperture ÷ magnification, the width of the light beam leaving the eyepiece — a big 4–7 mm exit pupil for bright wide views of nebulae, a small 0.5–2 mm for the Moon and planets at high power. The resolution endpoint gives the Dawes limit ≈ 116 ÷ aperture(mm) and the slightly stricter Rayleigh limit ≈ 138 ÷ aperture in arcseconds, plus the limiting magnitude ≈ 2.7 + 5·log₁₀(aperture mm) — bigger glass splits finer doubles and reaches fainter stars, though seeing usually caps real resolution near 1 arcsecond. Everything is computed locally and deterministically, so it is instant and private. Ideal for astronomy and stargazing apps, telescope-shop and eyepiece-calculator tools, and observing-planner utilities. Pure local computation — no key, no third-party service, instant. 3 compute endpoints. For camera/thin-lens imaging use a lens API; for stellar magnitudes a star-magnitude 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/telescope-api/..."
```

## Pricing
- **Free** (Free) — 9,200 calls/Mo, 2 req/s
- **Starter** ($7/Mo) — 90,000 calls/Mo, 6 req/s
- **Pro** ($26/Mo) — 366,000 calls/Mo, 15 req/s
- **Mega** ($79/Mo) — 1,680,000 calls/Mo, 40 req/s

## Endpoints

### Telescope

#### `GET /v1/exit-pupil` — Exit pupil

**Parameters:**
- `aperture_mm` (query, required, string) — Aperture (mm) Example: `200`
- `magnification` (query, required, string) — Magnification Example: `100`

**Example:**
```bash
curl -H "x-oanor-key: $KEY" \
  "https://api.oanor.com/telescope-api/v1/exit-pupil?aperture_mm=200&magnification=100"
```

**Response:**
```json
{
    "data": {
        "note": "Exit pupil = aperture ÷ magnification — the width of the beam of light leaving the eyepiece. Match it to the job: a big 4–7 mm exit pupil gives a bright, wide view for nebulae and the Milky Way (but beyond ~7 mm, more than a dark-adapted eye, light is wasted), while a small ~0.5–2 mm exit pupil at high power suits the Moon, planets and double stars. The exit pupil also sets the image brightness per unit area.",
        "inputs": {
            "aperture_mm": 200,
            "magnification": 100
        },
        "exit_pupil_mm": 2
    },
    "meta": {
        "timestamp": "2026-06-07T08:18:03.694Z",
        "request_id": "c25aba4c-d2fd-4795-a742-8ae6390d2668"
    },
    "status": "ok",
    "message": "Exit pupil",
    "success": true
}
```

#### `GET /v1/magnification` — Magnification and useful range

**Parameters:**
- `scope_focal_length_mm` (query, required, string) — Telescope focal length (mm) Example: `1000`
- `eyepiece_focal_length_mm` (query, required, string) — Eyepiece focal length (mm) Example: `10`
- `aperture_mm` (query, optional, string) — Aperture (mm) for useful range & f-ratio Example: `200`
- `apparent_fov_deg` (query, optional, string) — Eyepiece apparent field (deg) for true FOV Example: `52`

**Example:**
```bash
curl -H "x-oanor-key: $KEY" \
  "https://api.oanor.com/telescope-api/v1/magnification?scope_focal_length_mm=1000&eyepiece_focal_length_mm=10&aperture_mm=200&apparent_fov_deg=52"
```

**Response:**
```json
{
    "data": {
        "note": "Magnification = the telescope's focal length ÷ the eyepiece focal length, so a shorter eyepiece magnifies more. Useful magnification runs from about the aperture in mm ÷ 7 (a 7 mm exit pupil, lowest useful) up to roughly 2× the aperture in mm — push past that and the image just gets dim and fuzzy, not more detailed. The true field of view = the eyepiece's apparent field ÷ the magnification, so high power shows a small patch of sky.",
        "inputs": {
            "aperture_mm": 200,
            "apparent_fov_deg": 52,
            "scope_focal_length_mm": 1000,
            "eyepiece_focal_length_mm": 10
        },
        "focal_ratio": 5,
        "magnification": 100,
        "true_field_of_view_deg": 0.52,
        "max_useful_magnification": 400,
        "min_useful_magnification": 28.6
    },
    "meta": {
        "timestamp": "2026-06-07T08:18:03.768Z",
        "request_id": "98ee3446-a6a8-4640-aca2-20c31a399d55"
    },
    "status": "ok",
    "message": "Magnification",
    "success": true
}
```

#### `GET /v1/resolution` — Resolving power and limiting magnitude

**Parameters:**
- `aperture_mm` (query, required, string) — Aperture (mm) Example: `200`

**Example:**
```bash
curl -H "x-oanor-key: $KEY" \
  "https://api.oanor.com/telescope-api/v1/resolution?aperture_mm=200"
```

**Response:**
```json
{
    "data": {
        "note": "Resolving power is set by the aperture alone: the Dawes limit ≈ 116 ÷ aperture(mm) arcseconds is the classic split-a-double-star figure, the Rayleigh limit ≈ 138 ÷ aperture a slightly stricter criterion. Bigger glass resolves finer detail and, gathering more light, also reaches fainter stars — the limiting magnitude ≈ 2.7 + 5·log₁₀(aperture mm). Atmospheric seeing usually caps real resolution around 1 arcsecond regardless of aperture.",
        "inputs": {
            "aperture_mm": 200
        },
        "dawes_limit_arcsec": 0.58,
        "limiting_magnitude": 14.2,
        "rayleigh_limit_arcsec": 0.69
    },
    "meta": {
        "timestamp": "2026-06-07T08:18:03.856Z",
        "request_id": "22451984-dc3a-4a03-b49d-6d37fa0722b1"
    },
    "status": "ok",
    "message": "Resolution",
    "success": true
}
```

### Meta

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

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

**Response:**
```json
{
    "data": {
        "notes": "mm, degrees, arcseconds. mag = scope FL ÷ eyepiece FL; exit pupil = aperture ÷ mag; Dawes = 116/aperture, Rayleigh = 138/aperture; limiting mag = 2.7 + 5·log10(aperture mm). For camera/thin-lens imaging use a lens API; for stellar magnitudes a star-magnitude API.",
        "service": "telescope-api",
        "endpoints": {
            "GET /v1/meta": "This document.",
            "GET /v1/exit-pupil": "Exit pupil from aperture and magnification.",
            "GET /v1/resolution": "Dawes/Rayleigh resolution and limiting magnitude from aperture.",
            "GET /v1/magnification": "Magnification, focal ratio, useful range and true field of view."
        },
        "description": "Telescope optics maths: magnification and useful range, exit pupil, and resolving power / limiting magnitude."
    },
    "meta": {
        "timestamp": "2026-06-07T08:18:03.953Z",
        "request_id": "112e00f1-f88e-44d2-ac48-7a177e1bbf4b"
    },
    "status": "ok",
    "message": "Meta",
    "success": true
}
```


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