# Sea Horizon API
> Sea-horizon and visibility maths as an API, computed locally and deterministically — the distance-to-horizon, geographic-range and dip numbers a mariner, coastal navigator or marine app works sightings with. The horizon endpoint gives the distance to the sea horizon ≈ 1.169·√(height of eye in feet) nautical miles, including the standard atmospheric refraction that bends the line of sight a little past the geometric edge — at 9 ft of eye height the horizon is about 3.5 nm off — together with the dip, how far below true horizontal that watery edge lies (≈ 0.97′·√h), the correction subtracted from a sextant altitude shot to the sea horizon. The geographic-range endpoint gives how far off a light or landmark first peeps over the horizon = the sum of two horizon distances, your own plus the object's: 1.169·(√h_eye + √h_object), so a 100 ft lighthouse from a 9 ft cockpit lifts above the sea at about 15 nm — purely geometric, before the light's own luminous range and the visibility. The object-height endpoint inverts it: how tall a tower, light or headland must stand to break the horizon at a target range, or how close you must be before a known landmark appears. Everything is computed locally and deterministically, so it is instant and private. Ideal for marine-navigation and chartplotter apps, coastal-pilotage and lighthouse tools, and sailing utilities. Pure local computation — no key, no third-party service, instant. Geometric/refraction model. 3 compute endpoints. For great-circle distance use a geo-distance API; for set & drift a set-and-drift 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/horizon-api/..."
```

## Pricing
- **Free** (Free) — 8,400 calls/Mo, 2 req/s
- **Starter** ($8/Mo) — 87,000 calls/Mo, 6 req/s
- **Pro** ($28/Mo) — 358,000 calls/Mo, 15 req/s
- **Mega** ($88/Mo) — 1,665,000 calls/Mo, 40 req/s

## Endpoints

### Horizon

#### `GET /v1/geographic-range` — Range a light/landmark is first seen

**Parameters:**
- `eye_height_ft` (query, required, string) — Height of eye (ft) Example: `9`
- `object_height_ft` (query, required, string) — Object height (ft) Example: `100`

**Example:**
```bash
curl -H "x-oanor-key: $KEY" \
  "https://api.oanor.com/horizon-api/v1/geographic-range?eye_height_ft=9&object_height_ft=100"
```

**Response:**
```json
{
    "data": {
        "note": "The geographic range — how far off a light or landmark first peeps over the horizon — is the sum of two horizon distances: your own (from height of eye) plus the object's (from its height): 1.169·(√h_eye + √h_object). A 100 ft lighthouse seen from a 9 ft cockpit lifts above the sea at about 15 nm. It is purely geometric; whether you actually SEE it also needs the light's luminous range (its brightness) and the visibility.",
        "inputs": {
            "eye_height_ft": 9,
            "object_height_ft": 100
        },
        "geographic_range_km": 28.145,
        "geographic_range_nm": 15.197
    },
    "meta": {
        "timestamp": "2026-06-07T08:17:58.488Z",
        "request_id": "e2dfea0e-9433-40a6-8800-95740b963436"
    },
    "status": "ok",
    "message": "Geographic range",
    "success": true
}
```

#### `GET /v1/horizon` — Distance to sea horizon and dip

**Parameters:**
- `eye_height_ft` (query, required, string) — Height of eye (ft) Example: `9`

**Example:**
```bash
curl -H "x-oanor-key: $KEY" \
  "https://api.oanor.com/horizon-api/v1/horizon?eye_height_ft=9"
```

**Response:**
```json
{
    "data": {
        "note": "The distance to the sea horizon ≈ 1.169·√(height of eye in feet) nautical miles, including the standard atmospheric refraction that bends the line of sight a little past the geometric edge — at 9 ft of eye height the horizon is about 3.5 nm off. The dip is how far below the true horizontal that watery edge lies (≈ 0.97'·√h), the correction a navigator subtracts from a sextant altitude shot to the sea horizon.",
        "inputs": {
            "eye_height_ft": 9
        },
        "dip_arcmin": 2.91,
        "distance_to_horizon_km": 6.495,
        "distance_to_horizon_nm": 3.507
    },
    "meta": {
        "timestamp": "2026-06-07T08:17:58.591Z",
        "request_id": "2a886016-e0ff-4d14-9335-07632ea90693"
    },
    "status": "ok",
    "message": "Distance to horizon",
    "success": true
}
```

#### `GET /v1/object-height` — Object height for a target range

**Parameters:**
- `range_nm` (query, required, string) — Target range (nm) Example: `15.2`
- `eye_height_ft` (query, required, string) — Height of eye (ft) Example: `9`

**Example:**
```bash
curl -H "x-oanor-key: $KEY" \
  "https://api.oanor.com/horizon-api/v1/object-height?range_nm=15.2&eye_height_ft=9"
```

**Response:**
```json
{
    "data": {
        "note": "Turning the geographic-range formula around: the object height needed to be seen at a target range = (range ÷ 1.169 − √eye_height)², in feet. It is how tall a tower, light or headland must stand to break the horizon at the distance you want — or, the other way, how close you must be before a known landmark of a given height appears.",
        "inputs": {
            "range_nm": 15.2,
            "eye_height_ft": 9
        },
        "object_height_ft": 100.05
    },
    "meta": {
        "timestamp": "2026-06-07T08:17:58.683Z",
        "request_id": "17f0caa9-ae57-4285-966c-23e871e0eb23"
    },
    "status": "ok",
    "message": "Object height",
    "success": true
}
```

### Meta

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

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

**Response:**
```json
{
    "data": {
        "notes": "Feet, nm, arcmin (standard refraction). horizon = 1.169·√h_ft; dip = 0.97·√h_ft; geographic range = 1.169·(√h_eye+√h_obj). Geometric only — for luminous range use the light's nominal range. For great-circle distance use a geo-distance API.",
        "service": "horizon-api",
        "endpoints": {
            "GET /v1/meta": "This document.",
            "GET /v1/horizon": "Distance to the sea horizon and dip from the height of eye.",
            "GET /v1/object-height": "Object height needed to be seen at a target range.",
            "GET /v1/geographic-range": "Range a light/landmark is first seen (eye + object)."
        },
        "description": "Sea-horizon and visibility maths: distance to the horizon and dip, geographic range of a light, and object height for a range."
    },
    "meta": {
        "timestamp": "2026-06-07T08:17:58.775Z",
        "request_id": "c012a832-4d03-4d0e-b5d8-6dcbde6dff4d"
    },
    "status": "ok",
    "message": "Meta",
    "success": true
}
```


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