# Fiber Optic Link Budget API
> Fiber-optic link-budget engineering maths as an API, computed locally and deterministically — the power-budget, loss and reach numbers a network or fibre engineer designs an optical link with. The power-budget endpoint gives the optical power budget = transmit power − receiver sensitivity (in dBm), the total loss the link can tolerate: a 0 dBm transmitter into a −23 dBm receiver gives a 23 dB budget, with the powers also shown in milliwatts. The loss endpoint adds up the real link loss from the fibre attenuation × length plus the connector and splice losses — single-mode fibre runs about 0.35 dB/km at 1310 nm and 0.20 dB/km at 1550 nm, each mated connector ~0.5 dB and each fusion splice ~0.1 dB — so 10 km of fibre with two connectors is 4.5 dB. The reach endpoint gives the maximum distance = (power budget − fixed losses − system margin) ÷ the fibre attenuation, reserving a margin (typically 3 dB) for ageing, bends and future repair splices so the link still works years on. Everything is computed locally and deterministically, so it is instant and private. Ideal for FTTx and data-centre link planning, network-engineering and OSP tools, fibre-survey and design utilities, and telecom calculators. Pure local computation — no key, no third-party service, instant. Loss-limited model — at high bit rates dispersion can cap distance first. 3 compute endpoints. For fibre numerical aperture and photonics use a fiber API; for RF line-of-sight a Fresnel-zone 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/opticalbudget-api/..."
```

## Pricing
- **Free** (Free) — 5,600 calls/Mo, 2 req/s
- **Starter** ($12/Mo) — 57,000 calls/Mo, 6 req/s
- **Pro** ($38/Mo) — 238,000 calls/Mo, 15 req/s
- **Mega** ($116/Mo) — 1,190,000 calls/Mo, 40 req/s

## Endpoints

### Link

#### `GET /v1/loss` — Total link loss

**Parameters:**
- `length_km` (query, required, string) — Fiber length (km) Example: `10`
- `attenuation_db_km` (query, optional, string) — Fiber attenuation (dB/km, default 0.35) Example: `0.35`
- `connectors` (query, optional, string) — Connector pairs (default 2) Example: `2`
- `connector_loss_db` (query, optional, string) — Loss per connector (dB, default 0.5) Example: `0.5`
- `splices` (query, optional, string) — Splices (default 0) Example: `0`
- `splice_loss_db` (query, optional, string) — Loss per splice (dB, default 0.1) Example: `0.1`

**Example:**
```bash
curl -H "x-oanor-key: $KEY" \
  "https://api.oanor.com/opticalbudget-api/v1/loss?length_km=10&attenuation_db_km=0.35&connectors=2&connector_loss_db=0.5&splices=0&splice_loss_db=0.1"
```

**Response:**
```json
{
    "data": {
        "note": "Total link loss = fibre attenuation × length + the connector and splice losses. Single-mode fibre runs ~0.35 dB/km at 1310 nm and ~0.20 dB/km at 1550 nm; each mated connector pair costs ~0.3–0.75 dB and each fusion splice ~0.1 dB. Over long hauls the fibre dominates; on short patch links the connectors do. Compare this total against the power budget — the difference is your margin.",
        "inputs": {
            "splices": 0,
            "length_km": 10,
            "connectors": 2,
            "splice_loss_db": 0.1,
            "attenuation_db_km": 0.35,
            "connector_loss_db": 0.5
        },
        "fiber_loss_db": 3.5,
        "total_loss_db": 4.5,
        "splice_loss_db_total": 0,
        "connector_loss_db_total": 1
    },
    "meta": {
        "timestamp": "2026-06-07T08:18:07.216Z",
        "request_id": "6d4e57ac-b592-48bf-8366-1f5e6095971d"
    },
    "status": "ok",
    "message": "Link loss",
    "success": true
}
```

#### `GET /v1/power-budget` — Optical power budget

**Parameters:**
- `tx_power_dbm` (query, required, string) — Transmit power (dBm) Example: `0`
- `rx_sensitivity_dbm` (query, required, string) — Receiver sensitivity (dBm) Example: `-23`

**Example:**
```bash
curl -H "x-oanor-key: $KEY" \
  "https://api.oanor.com/opticalbudget-api/v1/power-budget?tx_power_dbm=0&rx_sensitivity_dbm=-23"
```

**Response:**
```json
{
    "data": {
        "note": "The optical power budget = transmit power − receiver sensitivity (both in dBm), the total loss the link can tolerate. A 0 dBm transmitter into a −23 dBm receiver gives a 23 dB budget. Everything between — fibre attenuation, connectors, splices — must fit inside it, with a margin left over for ageing and repairs. Because dBm is logarithmic, subtracting dBm gives dB of budget directly.",
        "inputs": {
            "tx_power_dbm": 0,
            "rx_sensitivity_dbm": -23
        },
        "tx_power_mw": 1,
        "power_budget_db": 23,
        "rx_sensitivity_mw": 0.005011872
    },
    "meta": {
        "timestamp": "2026-06-07T08:18:07.317Z",
        "request_id": "ff995d99-a6a4-4bfa-a853-376ca05b7ee5"
    },
    "status": "ok",
    "message": "Power budget",
    "success": true
}
```

#### `GET /v1/reach` — Maximum reach

**Parameters:**
- `tx_power_dbm` (query, required, string) — Transmit power (dBm) Example: `0`
- `rx_sensitivity_dbm` (query, required, string) — Receiver sensitivity (dBm) Example: `-23`
- `attenuation_db_km` (query, optional, string) — Fiber attenuation (dB/km, default 0.35) Example: `0.35`
- `fixed_loss_db` (query, optional, string) — Connector + splice loss (dB, default 2) Example: `2`
- `system_margin_db` (query, optional, string) — System margin (dB, default 3) Example: `3`

**Example:**
```bash
curl -H "x-oanor-key: $KEY" \
  "https://api.oanor.com/opticalbudget-api/v1/reach?tx_power_dbm=0&rx_sensitivity_dbm=-23&attenuation_db_km=0.35&fixed_loss_db=2&system_margin_db=3"
```

**Response:**
```json
{
    "data": {
        "note": "Maximum reach = (power budget − fixed losses − system margin) ÷ the fibre attenuation. The margin (typically 3 dB) reserves headroom for ageing, temperature, bends and future repair splices, so the link still works years on. Lower-attenuation 1550 nm fibre stretches the reach; this assumes the link is loss-limited, not dispersion-limited — at high bit rates dispersion can cap distance first.",
        "inputs": {
            "tx_power_dbm": 0,
            "fixed_loss_db": 2,
            "system_margin_db": 3,
            "attenuation_db_km": 0.35,
            "rx_sensitivity_dbm": -23
        },
        "max_distance_km": 51.429,
        "power_budget_db": 23,
        "usable_for_fiber_db": 18
    },
    "meta": {
        "timestamp": "2026-06-07T08:18:07.417Z",
        "request_id": "748c6e17-4e76-4220-bca8-b6eb4da38aee"
    },
    "status": "ok",
    "message": "Max reach",
    "success": true
}
```

### Meta

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

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

**Response:**
```json
{
    "data": {
        "notes": "dBm, dB, dB/km, km. budget = Tx − Rx; loss = α·L + connectors + splices; reach = (budget − fixed − margin)/α. SMF ≈ 0.35 dB/km @1310 nm, 0.20 @1550 nm. Loss-limited; dispersion may cap distance at high bit rates. For fibre NA/photonics use a fiber API; for RF line-of-sight a Fresnel-zone API.",
        "service": "opticalbudget-api",
        "endpoints": {
            "GET /v1/loss": "Total link loss from fiber, connectors and splices.",
            "GET /v1/meta": "This document.",
            "GET /v1/reach": "Maximum reach from the budget, attenuation and margin.",
            "GET /v1/power-budget": "Power budget from transmit power and receiver sensitivity."
        },
        "description": "Fiber-optic link-budget maths: optical power budget, total link loss, and maximum reach."
    },
    "meta": {
        "timestamp": "2026-06-07T08:18:07.522Z",
        "request_id": "11c28c29-d89e-406d-88ee-4fa2190b10f8"
    },
    "status": "ok",
    "message": "Meta",
    "success": true
}
```


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