# Lighting Calculator API
> Lighting design maths as an API, computed locally and deterministically. The room endpoint works out how many lumens a room needs from its area and a target illuminance — given directly in lux or chosen from a room-type preset (living, kitchen, office, workshop and more) — and, optionally, how many fixtures at a given lumen output and how many watts at a given lamp type. The lux endpoint converts between lux, footcandles and lumens over an area, so you can find the illuminance from a light output and a room size or vice versa. The efficacy endpoint relates lumens, watts and luminous efficacy (lumens per watt): give any two — or a lamp-type preset such as incandescent, halogen, CFL or LED — and it computes the third. Everything is computed locally and deterministically, so it is instant and private. It is a lumen-method estimate: target levels are typical guidance (EN 12464 / IES) and a full design would add room and utilisation factors. Ideal for lighting and electrical tools, interior-design and home apps, retrofit and energy-saving calculators, and smart-home planning. Pure local computation — no key, no third-party service, instant. Live, nothing stored. 3 endpoints. This is illumination maths; for Ohm's-law electrical quantities use an electronics 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/lighting-api/..."
```

## Pricing
- **Free** (Free) — 10,335 calls/Mo, 2 req/s
- **Starter** ($12/Mo) — 19,950 calls/Mo, 8 req/s
- **Pro** ($32/Mo) — 249,500 calls/Mo, 20 req/s
- **Mega** ($70/Mo) — 1,290,000 calls/Mo, 50 req/s

## Endpoints

### Lighting

#### `GET /v1/efficacy` — Lumens / watts / efficacy

**Parameters:**
- `lumens` (query, optional, string) — Lumens Example: `800`
- `watts` (query, optional, string) — Watts
- `efficacy` (query, optional, string) — lm/W
- `bulb_type` (query, optional, string) — led|cfl|halogen|incandescent Example: `led`

**Example:**
```bash
curl -H "x-oanor-key: $KEY" \
  "https://api.oanor.com/lighting-api/v1/efficacy?lumens=800&bulb_type=led"
```

**Response:**
```json
{
    "data": {
        "note": "Luminous efficacy (lm/W) relates light output to power. Presets: incandescent 14, halogen 20, CFL 60, fluorescent 80, LED 90.",
        "input": {
            "watts": null,
            "lumens": 800,
            "efficacy": 90,
            "bulb_type": "led"
        },
        "watts": 8.89,
        "lumens": 800,
        "efficacy_lm_per_w": 90
    },
    "meta": {
        "timestamp": "2026-06-03T17:41:54.976Z",
        "request_id": "d984cdaa-8a91-4936-8db7-d10c68c4d598"
    },
    "status": "ok",
    "message": "Lumens / watts / efficacy",
    "success": true
}
```

#### `GET /v1/lux` — Lux / footcandle / lumens

**Parameters:**
- `lumens` (query, optional, string) — Light output Example: `10000`
- `area` (query, optional, string) — Area m² Example: `20`
- `lux` (query, optional, string) — Or a lux value
- `footcandles` (query, optional, string) — Or footcandles

**Example:**
```bash
curl -H "x-oanor-key: $KEY" \
  "https://api.oanor.com/lighting-api/v1/lux?lumens=10000&area=20"
```

**Response:**
```json
{
    "data": {
        "lux": 500,
        "note": "Illuminance: lux = lumens ÷ area (m²). 1 footcandle = 10.764 lux.",
        "lumens": 10000,
        "area_m2": 20,
        "footcandles": 46.452
    },
    "meta": {
        "timestamp": "2026-06-03T17:41:55.055Z",
        "request_id": "63b2be74-18fa-48f9-ba68-6670be433643"
    },
    "status": "ok",
    "message": "Lux / footcandle conversion",
    "success": true
}
```

#### `GET /v1/room` — Lumens needed for a room

**Parameters:**
- `area` (query, optional, string) — Area (or length+width) Example: `20`
- `area_unit` (query, optional, string) — sqm|sqft Example: `sqm`
- `room_type` (query, optional, string) — office|kitchen|living|… Example: `office`
- `lux` (query, optional, string) — Or explicit target lux
- `lumens_per_fixture` (query, optional, string) — For fixture count
- `bulb_type` (query, optional, string) — led|cfl|halogen|incandescent (for watts)

**Example:**
```bash
curl -H "x-oanor-key: $KEY" \
  "https://api.oanor.com/lighting-api/v1/room?area=20&area_unit=sqm&room_type=office"
```

**Response:**
```json
{
    "data": {
        "note": "Lumens = area (m²) × target lux. Target levels are typical guidance; this is a lumen-method estimate (no room/utilisation factors).",
        "input": {
            "area_m2": 20,
            "room_type": "office",
            "target_lux": 500
        },
        "footcandles": 46.45,
        "total_lumens": 10000,
        "lumens_per_m2": 500
    },
    "meta": {
        "timestamp": "2026-06-03T17:41:55.144Z",
        "request_id": "f7ebaef5-be73-4c75-901c-6149c4d52ed6"
    },
    "status": "ok",
    "message": "Lumens for a room",
    "success": true
}
```

### Meta

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

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

**Response:**
```json
{
    "data": {
        "note": "Lumen-method estimate; target levels are typical guidance (EN 12464 / IES). Add room/utilisation factors for a full design.",
        "service": "lighting",
        "endpoints": {
            "/v1/lux": "Convert between lux, footcandles and lumens over an area.",
            "/v1/room": "Total lumens (and fixtures/watts) for a room from its area and a target lux or room type.",
            "/v1/efficacy": "Convert between lumens, watts and luminous efficacy (lm/W), with lamp-type presets."
        },
        "bulb_types": [
            "incandescent",
            "halogen",
            "cfl",
            "fluorescent",
            "led",
            "hps",
            "sodium"
        ],
        "room_types": [
            "living",
            "lounge",
            "bedroom",
            "hallway",
            "corridor",
            "garage",
            "closet",
            "kitchen",
            "bathroom",
            "diningroom",
            "laundry",
            "stairs",
            "office",
            "study",
            "classroom",
            "retail",
            "workshop",
            "kitchencounter",
            "warehouse",
            "supermarket",
            "drawingoffice",
            "surgery",
            "garageworkshop"
        ],
        "description": "Lighting maths: lumens needed for a room, lux/footcandle conversion, and lumens↔watts via luminous efficacy."
    },
    "meta": {
        "timestamp": "202
…(truncated, see openapi.json for full schema)
```


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