# 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"
```

#### `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"
```

#### `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"
```

### Meta

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

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


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