# Sonar & Underwater Sound API
> Underwater-sound and sonar maths as an API, computed locally and deterministically — the speed, absorption and ranging numbers a marine engineer, sonar developer or oceanographer works with. The sound-speed endpoint gives the speed of sound in seawater from the Mackenzie nine-term equation: about 1,500 m/s — far faster than in air — rising with temperature, salinity and depth, so a profile of 25 °C, 35 ppt at 1,000 m gives 1,550.7 m/s. Because the speed varies with depth, sound rays bend and form the SOFAR channel that carries whale song and signals across whole oceans. The absorption endpoint gives Thorp's sound-absorption coefficient in dB per km against frequency, with the loss over a path: seawater swallows high frequencies fast, which is why long-range sonar and whale calls are low-pitched while high-frequency sonar gives sharp images only at short range. The echo-range endpoint turns an echo sounder's or sonar's two-way travel time into the range or depth — distance = sound speed × time ÷ 2 — so a one-second round trip at 1,500 m/s is a target 750 m away, its accuracy resting on the assumed sound speed. Everything is computed locally and deterministically, so it is instant and private. Ideal for sonar and hydrophone tools, marine-survey and bathymetry apps, ocean-acoustics research, and AUV/ROV navigation utilities. Pure local computation — no key, no third-party service, instant. Standard-equation estimates over their valid ranges. 3 compute endpoints. For the speed of sound in air and Mach use a Mach-number API; for decibels a sound-level 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/sonar-api/..."
```

## Pricing
- **Free** (Free) — 4,300 calls/Mo, 2 req/s
- **Starter** ($13/Mo) — 46,000 calls/Mo, 6 req/s
- **Pro** ($40/Mo) — 208,000 calls/Mo, 15 req/s
- **Mega** ($126/Mo) — 1,100,000 calls/Mo, 40 req/s

## Endpoints

### Sonar

#### `GET /v1/absorption` — Sound absorption vs frequency

**Parameters:**
- `frequency_khz` (query, required, string) — Frequency (kHz) Example: `10`
- `range_km` (query, optional, string) — Path length for total loss (km) Example: `5`

**Example:**
```bash
curl -H "x-oanor-key: $KEY" \
  "https://api.oanor.com/sonar-api/v1/absorption?frequency_khz=10&range_km=5"
```

**Response:**
```json
{
    "data": {
        "note": "Seawater absorbs sound more strongly at higher frequencies (Thorp's formula): low frequencies travel far, which is why long-range sonar and whale calls are low-pitched, while high-frequency sonar gives sharp images but only at short range. The loss adds to the spreading loss, so doubling the frequency roughly quadruples the absorption at sonar frequencies. Near-surface, ~4 °C water.",
        "inputs": {
            "range_km": 5,
            "frequency_khz": 10
        },
        "absorption_loss_db": 5.94,
        "absorption_db_per_km": 1.187
    },
    "meta": {
        "timestamp": "2026-06-06T23:53:52.010Z",
        "request_id": "7cccc13d-7ad1-46c2-bdb0-6b45f989fd6e"
    },
    "status": "ok",
    "message": "Absorption",
    "success": true
}
```

#### `GET /v1/echo-range` — Range/depth from echo travel time

**Parameters:**
- `travel_time_s` (query, required, string) — Two-way travel time (s) Example: `1`
- `sound_speed_m_s` (query, optional, string) — Sound speed (m/s, default 1500) Example: `1500`

**Example:**
```bash
curl -H "x-oanor-key: $KEY" \
  "https://api.oanor.com/sonar-api/v1/echo-range?travel_time_s=1&sound_speed_m_s=1500"
```

**Response:**
```json
{
    "data": {
        "note": "An echo sounder or sonar measures the two-way travel time, so the distance to the bottom or target = sound speed × time ÷ 2 (the sound goes out and comes back). At a typical 1,500 m/s, a one-second round trip is 750 m away. The accuracy rests on the assumed sound speed, which is why survey-grade echo sounders measure the real sound-speed profile (see /v1/sound-speed) rather than assume it.",
        "inputs": {
            "travel_time_s": 1,
            "sound_speed_m_s": 1500
        },
        "range_m": 750,
        "range_km": 0.75
    },
    "meta": {
        "timestamp": "2026-06-06T23:53:52.091Z",
        "request_id": "47a3d0ab-af18-4245-b593-55c545162508"
    },
    "status": "ok",
    "message": "Echo range",
    "success": true
}
```

#### `GET /v1/sound-speed` — Speed of sound in seawater

**Parameters:**
- `temp_c` (query, required, string) — Water temperature (°C) Example: `25`
- `salinity_ppt` (query, optional, string) — Salinity (ppt, default 35) Example: `35`
- `depth_m` (query, optional, string) — Depth (m, default 0) Example: `1000`

**Example:**
```bash
curl -H "x-oanor-key: $KEY" \
  "https://api.oanor.com/sonar-api/v1/sound-speed?temp_c=25&salinity_ppt=35&depth_m=1000"
```

**Response:**
```json
{
    "data": {
        "note": "The speed of sound in seawater from the Mackenzie equation — about 1,500 m/s, far faster than in air, and it rises with temperature, salinity and depth (pressure). Because those vary with depth the speed forms a profile that bends sound rays, creating the SOFAR channel that carries whale song and submarine signals for thousands of kilometres. Valid roughly 2–30 °C, 25–40 ppt and to 8,000 m.",
        "inputs": {
            "temp_c": 25,
            "depth_m": 1000,
            "salinity_ppt": 35
        },
        "sound_speed_m_s": 1550.74
    },
    "meta": {
        "timestamp": "2026-06-06T23:53:52.176Z",
        "request_id": "083e2663-493c-47a0-a067-b929433bc7ff"
    },
    "status": "ok",
    "message": "Sound speed",
    "success": true
}
```

### Meta

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

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

**Response:**
```json
{
    "data": {
        "notes": "Metric (°C, ppt, m, kHz, dB, m/s, s). Mackenzie nine-term sound speed; Thorp absorption; range = c·t/2. For the speed of sound in air / Mach use a Mach-number API; for decibels a sound-level API.",
        "service": "sonar-api",
        "endpoints": {
            "GET /v1/meta": "This document.",
            "GET /v1/absorption": "Sound absorption (dB/km) vs frequency, with optional path loss.",
            "GET /v1/echo-range": "Range or depth from an echo's two-way travel time.",
            "GET /v1/sound-speed": "Speed of sound in seawater from temperature, salinity and depth."
        },
        "description": "Underwater-sound / sonar maths: speed of sound in seawater (Mackenzie), Thorp absorption vs frequency, and echo range from two-way travel time."
    },
    "meta": {
        "timestamp": "2026-06-06T23:53:52.270Z",
        "request_id": "06fb03c9-e7e5-4b4f-a320-7121c04ed68d"
    },
    "status": "ok",
    "message": "Meta",
    "success": true
}
```


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