# Snell Refraction API
> Snell's-law refraction optics as an API, computed locally and deterministically. The refraction endpoint applies Snell's law, n1·sin(θ1) = n2·sin(θ2): from the refractive indices of two media (given directly or by material — vacuum, air, water, glass, diamond and more) and the angle of incidence it returns the angle of refraction, or solves for the incidence angle from a refraction angle; when light passes into a less dense medium beyond the critical angle it reports total internal reflection instead of a refracted ray. The critical-angle endpoint gives the threshold for total internal reflection, θc = asin(n2/n1) for n1 > n2 — the principle behind optical fibres — defaulting the exit medium to air. The speed endpoint gives the speed of light in a medium, v = c/n, as a fraction of c, and — with a vacuum wavelength — the shorter wavelength inside the medium (the frequency is unchanged). Angles are in degrees, wavelengths in nanometres. Everything is computed locally and deterministically, so it is instant and private. Ideal for optics and photonics tools, fibre-optic and lens-design apps, photography and physics education, and AR/VR and rendering software. Pure local computation — no key, no third-party service, instant. Live, nothing stored. 3 endpoints. This is Snell's-law refraction; for camera depth of field and field of view use a photography 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/snell-api/..."
```

## Pricing
- **Free** (Free) — 2,000 calls/Mo, 2 req/s
- **Starter** ($5/Mo) — 25,000 calls/Mo, 5 req/s
- **Pro** ($15/Mo) — 150,000 calls/Mo, 15 req/s
- **Mega** ($45/Mo) — 753,000 calls/Mo, 40 req/s

## Endpoints

### Optics

#### `GET /v1/critical-angle` — Critical angle (TIR)

**Parameters:**
- `index_1` (query, optional, string) — Denser medium index (or material_1) Example: `1.333`
- `material_1` (query, optional, string) — Denser material Example: `water`
- `index_2` (query, optional, string) — Exit medium index (default air)
- `material_2` (query, optional, string) — Exit material (default air)

**Example:**
```bash
curl -H "x-oanor-key: $KEY" \
  "https://api.oanor.com/snell-api/v1/critical-angle?index_1=1.333&material_1=water"
```

**Response:**
```json
{
    "data": {
        "note": "At incidence angles beyond the critical angle, light is totally internally reflected (the basis of optical fibres).",
        "formula": "θc = asin(n2 / n1).",
        "index_1": 1.333,
        "index_2": 1.0003,
        "medium_1": "explicit",
        "medium_2": "air",
        "critical_angle_deg": 48.62613
    },
    "meta": {
        "timestamp": "2026-06-04T10:18:57.187Z",
        "request_id": "81b6b88c-aa88-48f4-8186-6978a8d34a0b"
    },
    "status": "ok",
    "message": "Critical angle (TIR)",
    "success": true
}
```

#### `GET /v1/refraction` — Snell's law refraction

**Parameters:**
- `index_1` (query, optional, string) — Refractive index of medium 1 (or material_1) Example: `1.0`
- `material_1` (query, optional, string) — air|water|glass|… (instead of index_1) Example: `air`
- `index_2` (query, optional, string) — Refractive index of medium 2 (or material_2) Example: `1.333`
- `material_2` (query, optional, string) — Material of medium 2 Example: `water`
- `angle_1` (query, optional, string) — Angle of incidence (deg) Example: `30`
- `angle_2` (query, optional, string) — Or angle of refraction (to get incidence)

**Example:**
```bash
curl -H "x-oanor-key: $KEY" \
  "https://api.oanor.com/snell-api/v1/refraction?index_1=1.0&material_1=air&index_2=1.333&material_2=water&angle_1=30"
```

**Response:**
```json
{
    "data": {
        "formula": "n1·sin(θ1) = n2·sin(θ2).",
        "index_1": 1,
        "index_2": 1.333,
        "medium_1": "explicit",
        "medium_2": "explicit",
        "incidence_angle_deg": 30,
        "refraction_angle_deg": 22.03011,
        "total_internal_reflection": false
    },
    "meta": {
        "timestamp": "2026-06-04T10:18:57.283Z",
        "request_id": "5bb935de-b93a-4f63-b868-67c180dc09fe"
    },
    "status": "ok",
    "message": "Snell's law refraction",
    "success": true
}
```

#### `GET /v1/speed` — Speed of light in a medium

**Parameters:**
- `index` (query, optional, string) — Refractive index (or material) Example: `1.333`
- `material` (query, optional, string) — water|glass|diamond|… Example: `water`
- `vacuum_wavelength_nm` (query, optional, string) — Vacuum wavelength (for medium wavelength) Example: `600`

**Example:**
```bash
curl -H "x-oanor-key: $KEY" \
  "https://api.oanor.com/snell-api/v1/speed?index=1.333&material=water&vacuum_wavelength_nm=600"
```

**Response:**
```json
{
    "data": {
        "note": "Wavelength shortens by 1/n inside the medium; the frequency is unchanged.",
        "medium": "explicit",
        "refractive_index": 1.333,
        "speed_fraction_of_c": 0.750188,
        "speed_in_medium_m_s": 224900568.64,
        "vacuum_wavelength_nm": 600,
        "wavelength_in_medium_nm": 450.112528
    },
    "meta": {
        "timestamp": "2026-06-04T10:18:57.377Z",
        "request_id": "673faf42-1390-45f0-8e3e-812c227d141b"
    },
    "status": "ok",
    "message": "Speed of light in a medium",
    "success": true
}
```

### Meta

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

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

**Response:**
```json
{
    "data": {
        "api": "snell",
        "note": "Snell's-law refraction optics — computed locally and deterministically, no key, no third-party service.",
        "media": [
            "vacuum",
            "air",
            "water",
            "ice",
            "ethanol",
            "glycerin",
            "oil",
            "glass",
            "crown_glass",
            "quartz",
            "acrylic",
            "polycarbonate",
            "sapphire",
            "diamond",
            "zircon"
        ],
        "endpoints": [
            "/v1/refraction",
            "/v1/critical-angle",
            "/v1/speed",
            "/v1/meta"
        ],
        "speed_of_light_m_s": 299792458
    },
    "meta": {
        "timestamp": "2026-06-04T10:18:57.467Z",
        "request_id": "76263004-65ee-4e35-a9b3-fcbe4d45c5a1"
    },
    "status": "ok",
    "message": "Meta",
    "success": true
}
```


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