# Sound Level API
> Acoustics and decibel maths as an API. The decibel endpoint converts between a linear ratio and decibels, in either the power convention (10·log₁₀) or the amplitude/pressure convention (20·log₁₀), in both directions. The combine endpoint adds sound levels the way real (incoherent) sources combine — by energy summation, so two equal 80 dB sources give 83 dB, not 160 — and can also subtract a known source from a measured total. The distance endpoint applies the inverse-square law to a point source in a free field (−6 dB per doubling of distance) to find the level at a new distance. The wavelength endpoint converts between frequency and wavelength for sound, deriving the speed of sound from the air temperature (or a value you provide). Everything is computed locally and deterministically, so it is instant and private. Ideal for audio engineering and live sound, room and architectural acoustics, noise assessment and environmental monitoring, and physics teaching. Pure local computation — no key, no third-party service, instant. Live, nothing stored. 5 endpoints. This is acoustics maths; for electrical circuits use an Ohm's-law API and for general unit conversion use a unit 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/soundlevel-api/..."
```

## Pricing
- **Free** (Free) — 7,235 calls/Mo, 2 req/s
- **Starter** ($9/Mo) — 16,750 calls/Mo, 8 req/s
- **Pro** ($29/Mo) — 218,500 calls/Mo, 20 req/s
- **Mega** ($67/Mo) — 1,135,000 calls/Mo, 50 req/s

## Endpoints

### Sound

#### `GET /v1/combine` — Add/subtract sound levels

**Parameters:**
- `levels` (query, required, string) — List of dB values Example: `80,80`
- `mode` (query, optional, string) — add|subtract Example: `add`

**Example:**
```bash
curl -H "x-oanor-key: $KEY" \
  "https://api.oanor.com/soundlevel-api/v1/combine?levels=80%2C80&mode=add"
```

**Response:**
```json
{
    "data": {
        "mode": "add",
        "note": "incoherent (energy) summation",
        "levels": [
            80,
            80
        ],
        "total_db": 83.0103
    },
    "meta": {
        "timestamp": "2026-06-03T17:42:09.551Z",
        "request_id": "c7104f7c-8b62-46d2-bb7e-33379fb6a007"
    },
    "status": "ok",
    "message": "Combine levels",
    "success": true
}
```

#### `GET /v1/decibel` — Ratio <-> decibels

**Parameters:**
- `ratio` (query, optional, string) — A linear ratio Example: `2`
- `decibels` (query, optional, string) — Or a dB value
- `type` (query, optional, string) — power|amplitude Example: `power`

**Example:**
```bash
curl -H "x-oanor-key: $KEY" \
  "https://api.oanor.com/soundlevel-api/v1/decibel?ratio=2&type=power"
```

**Response:**
```json
{
    "data": {
        "type": "power",
        "ratio": 2,
        "factor": 10,
        "decibels": 3.0103
    },
    "meta": {
        "timestamp": "2026-06-03T17:42:09.648Z",
        "request_id": "1ff2c041-cc51-410a-8872-2f10eab7f910"
    },
    "status": "ok",
    "message": "Decibel",
    "success": true
}
```

#### `GET /v1/distance` — Distance attenuation

**Parameters:**
- `level` (query, required, string) — dB at d1 Example: `100`
- `from_distance` (query, required, string) — d1 Example: `1`
- `to_distance` (query, required, string) — d2 Example: `10`

**Example:**
```bash
curl -H "x-oanor-key: $KEY" \
  "https://api.oanor.com/soundlevel-api/v1/distance?level=100&from_distance=1&to_distance=10"
```

**Response:**
```json
{
    "data": {
        "note": "point source in free field (−6 dB per distance doubling)",
        "level_db": 100,
        "change_db": -20,
        "to_distance": 10,
        "new_level_db": 80,
        "from_distance": 1
    },
    "meta": {
        "timestamp": "2026-06-03T17:42:09.759Z",
        "request_id": "27d7384b-9e5b-466f-a5cc-f00cccec06ab"
    },
    "status": "ok",
    "message": "Distance attenuation",
    "success": true
}
```

#### `GET /v1/wavelength` — Wavelength <-> frequency

**Parameters:**
- `frequency` (query, optional, string) — Hz Example: `1000`
- `wavelength` (query, optional, string) — Or metres
- `temperature` (query, optional, string) — Air °C (default 20) Example: `20`
- `speed` (query, optional, string) — Or speed of sound m/s

**Example:**
```bash
curl -H "x-oanor-key: $KEY" \
  "https://api.oanor.com/soundlevel-api/v1/wavelength?frequency=1000&temperature=20"
```

**Response:**
```json
{
    "data": {
        "frequency_hz": 1000,
        "wavelength_m": 0.343215,
        "speed_of_sound_m_s": 343.215
    },
    "meta": {
        "timestamp": "2026-06-03T17:42:09.835Z",
        "request_id": "00f413fb-75fd-4c88-8799-18efd5ae1a48"
    },
    "status": "ok",
    "message": "Wavelength",
    "success": true
}
```

### Meta

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

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

**Response:**
```json
{
    "data": {
        "name": "Sound Level API",
        "notes": "Power: dB = 10·log₁₀(ratio). Amplitude/pressure: dB = 20·log₁₀(ratio). Levels combine by energy. Speed of sound ≈ 331.3·√(1+T/273.15) m/s. Nothing is stored.",
        "version": "v1",
        "endpoints": [
            {
                "path": "/v1/decibel",
                "params": {
                    "type": "power (10log) | amplitude (20log)",
                    "ratio": "a linear ratio (-> dB)",
                    "decibels": "or a dB value (-> ratio)"
                },
                "returns": "the conversion"
            },
            {
                "path": "/v1/combine",
                "params": {
                    "mode": "add | subtract",
                    "levels": "list of dB values"
                },
                "returns": "the combined sound level"
            },
            {
                "path": "/v1/distance",
                "params": {
                    "level": "dB at the first distance",
                    "to_distance": "d2",
                    "from_distance": "d1"
                },
                "returns": "the level at the new distance"
            },
            {
                "path": "/v1/wavelength",
                "params": {
                    "speed": "or speed of sound m/s",
                    "frequency": "Hz",
                    "wavelength": "or metres",
                    "temperature": "air °C (default 20)"
        
…(truncated, see openapi.json for full schema)
```


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