# Photometry & Lighting API
> Photometry and lighting maths as an API, computed locally and deterministically. The illuminance endpoint computes the light falling on a surface from a point source, E = I·cos(θ)/d² in lux, from the luminous intensity in candela, the distance in metres and the angle of incidence from the surface normal — a 1000 cd source straight down at 2 m gives 250 lux. The inverse-square endpoint scales a known illuminance to a new distance, E2 = E1·(d1/d2)², so doubling the distance quarters the light. The flux-intensity endpoint converts between luminous flux in lumens and luminous intensity in candela through the solid angle, I = Φ/Ω and Φ = I·Ω, with the solid angle taken as the full sphere 4π steradian for an isotropic source or, for a spotlight of full beam angle β, Ω = 2π·(1 − cos(β/2)) — so a 100 cd isotropic source emits about 1256.6 lm, and a 1000 cd lamp in a 30° beam emits about 214 lm. Distances are in metres and angles in degrees. Everything is computed locally and deterministically, so it is instant and private. Ideal for lighting-design, architecture, photography, film, horticulture-grow-light, stage and AV app developers, lux-and-lumen and luminaire-planning tools, and engineering software. Pure local computation — no key, no third-party service, instant. Live, nothing stored. 3 endpoints. These are photometric (perceived-light) quantities; for blackbody/peak-wavelength radiometry use a Wien/radiation 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/photometry-api/..."
```

## Pricing
- **Free** (Free) — 5,300 calls/Mo, 2 req/s
- **Starter** ($5/Mo) — 53,000 calls/Mo, 6 req/s
- **Pro** ($15/Mo) — 235,000 calls/Mo, 15 req/s
- **Mega** ($47/Mo) — 1,330,000 calls/Mo, 40 req/s

## Endpoints

### Photometry

#### `GET /v1/flux-intensity` — Flux ↔ intensity

**Parameters:**
- `flux` (query, optional, string) — Luminous flux (lm)
- `intensity` (query, optional, string) — Luminous intensity (cd) Example: `100`
- `beam_angle` (query, optional, string) — Full beam angle (deg)
- `solid_angle` (query, optional, string) — Solid angle (sr)

**Example:**
```bash
curl -H "x-oanor-key: $KEY" \
  "https://api.oanor.com/photometry-api/v1/flux-intensity?intensity=100"
```

**Response:**
```json
{
    "data": {
        "note": "Φ = I·Ω. A 100 cd isotropic source emits 100·4π ≈ 1256.6 lm.",
        "inputs": {
            "intensity": 100
        },
        "flux_lumen": 1256.637061,
        "solid_angle_sr": 12.56637061
    },
    "meta": {
        "timestamp": "2026-06-05T19:50:24.097Z",
        "request_id": "d329b480-76c9-4107-b354-679726f84b36"
    },
    "status": "ok",
    "message": "Flux/intensity conversion",
    "success": true
}
```

#### `GET /v1/illuminance` — Illuminance from a point source

**Parameters:**
- `intensity` (query, required, string) — Luminous intensity (cd) Example: `1000`
- `distance` (query, required, string) — Distance (m) Example: `2`
- `incidence_angle` (query, optional, string) — Angle of incidence (deg) Example: `0`

**Example:**
```bash
curl -H "x-oanor-key: $KEY" \
  "https://api.oanor.com/photometry-api/v1/illuminance?intensity=1000&distance=2&incidence_angle=0"
```

**Response:**
```json
{
    "data": {
        "note": "Point-source illuminance E = I·cos(θ)/d² (lux), with θ the angle of incidence from the surface normal. A 1000 cd source at 2 m gives 250 lux head-on.",
        "inputs": {
            "distance": 2,
            "intensity": 1000,
            "incidence_angle": 0
        },
        "illuminance_lux": 250
    },
    "meta": {
        "timestamp": "2026-06-05T19:50:24.198Z",
        "request_id": "83a6b870-8783-435d-8023-fbeb46094d57"
    },
    "status": "ok",
    "message": "Illuminance",
    "success": true
}
```

#### `GET /v1/inverse-square` — Inverse-square scaling

**Parameters:**
- `illuminance` (query, required, string) — Known illuminance (lux) Example: `250`
- `distance1` (query, required, string) — Known distance (m) Example: `2`
- `distance2` (query, required, string) — New distance (m) Example: `4`

**Example:**
```bash
curl -H "x-oanor-key: $KEY" \
  "https://api.oanor.com/photometry-api/v1/inverse-square?illuminance=250&distance1=2&distance2=4"
```

**Response:**
```json
{
    "data": {
        "note": "Inverse-square law E2 = E1·(d1/d2)². Doubling the distance quarters the illuminance.",
        "inputs": {
            "distance1": 2,
            "distance2": 4,
            "illuminance": 250
        },
        "illuminance_lux": 62.5
    },
    "meta": {
        "timestamp": "2026-06-05T19:50:24.300Z",
        "request_id": "1256f5a9-b387-4de9-a24d-06495b87da8f"
    },
    "status": "ok",
    "message": "Inverse-square law",
    "success": true
}
```

### Meta

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

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

**Response:**
```json
{
    "data": {
        "notes": "Distances in metres, angles in degrees. Photometric (perceived-light) quantities; for radiometric watts use a radiometry/Wien API and for sound levels a sound-level API.",
        "units": {
            "flux": "lumen (lm)",
            "intensity": "candela (cd)",
            "illuminance": "lux (lx = lm/m²)",
            "solid_angle": "steradian (sr)"
        },
        "service": "photometry-api",
        "endpoints": {
            "GET /v1/meta": "This document.",
            "GET /v1/illuminance": "Illuminance E = I·cosθ/d² from intensity and distance.",
            "GET /v1/flux-intensity": "Convert luminous flux ↔ intensity via beam/solid angle.",
            "GET /v1/inverse-square": "Scale illuminance to a new distance."
        },
        "description": "Photometry / lighting: illuminance (lux), the inverse-square law, and luminous flux (lm) ↔ intensity (cd) via solid angle."
    },
    "meta": {
        "timestamp": "2026-06-05T19:50:24.402Z",
        "request_id": "6078b875-abdb-465f-b65b-4a1d0a793bb2"
    },
    "status": "ok",
    "message": "Meta",
    "success": true
}
```


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