# Doppler Effect API
> Doppler-effect maths as an API, computed locally and deterministically. The sound endpoint computes the acoustic Doppler shift, f' = f·(v + vo) / (v − vs), where v is the speed of sound (given directly, derived from an air temperature, or the default 343 m/s at 20 °C), vs is the source velocity and vo the observer velocity, with positive velocities meaning approaching: it returns the observed frequency and the frequency shift, and refuses a supersonic source. The light endpoint computes the relativistic Doppler effect for light, f' = f·√((1+β)/(1−β)), from a velocity in metres per second or as a fraction of the speed of light and a direction (approaching blue-shifts, receding red-shifts), returning the frequency and wavelength factor, the observed frequency or wavelength, and the redshift z. The radial-velocity endpoint reverses it: from a measured redshift, or an observed and rest wavelength, it recovers the radial velocity with the exact relativistic relation and the simple v ≈ z·c estimate. Frequencies are in hertz, wavelengths in nanometres, velocities in metres per second. Everything is computed locally and deterministically, so it is instant and private. Ideal for physics and astronomy education, radar, sonar and lidar tools, audio and acoustics apps, and spectroscopy and redshift calculators. Pure local computation — no key, no third-party service, instant. Live, nothing stored. 3 endpoints. This is the Doppler effect; for sound levels and decibels use an acoustics 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/doppler-api/..."
```

## Pricing
- **Free** (Free) — 2,000 calls/Mo, 2 req/s
- **Starter** ($5/Mo) — 25,000 calls/Mo, 5 req/s
- **Pro** ($15/Mo) — 150,000 calls/Mo, 15 req/s
- **Mega** ($49/Mo) — 786,000 calls/Mo, 40 req/s

## Endpoints

### Doppler

#### `GET /v1/light` — Relativistic light Doppler / redshift

**Parameters:**
- `velocity` (query, optional, string) — Relative velocity (m/s)
- `beta` (query, optional, string) — Or velocity as a fraction of c Example: `0.1`
- `direction` (query, optional, string) — approaching|receding (default receding) Example: `receding`
- `frequency` (query, optional, string) — Emitted frequency (optional)
- `wavelength_nm` (query, optional, string) — Emitted wavelength nm (optional) Example: `656.3`

**Example:**
```bash
curl -H "x-oanor-key: $KEY" \
  "https://api.oanor.com/doppler-api/v1/light?beta=0.1&direction=receding&wavelength_nm=656.3"
```

**Response:**
```json
{
    "data": {
        "note": "Receding source: light is red-shifted (lower frequency, longer wavelength).",
        "formula": "f' = f·√((1+β)/(1−β)); z = λ_obs/λ_emit − 1.",
        "direction": "receding",
        "redshift_z": 0.1055416,
        "velocity_m_s": 29979245.8,
        "frequency_factor": 0.90453403,
        "velocity_fraction_c": 0.1,
        "emitted_wavelength_nm": 656.3,
        "observed_wavelength_nm": 725.56694997
    },
    "meta": {
        "timestamp": "2026-06-04T10:18:56.339Z",
        "request_id": "e0fb4486-b9c1-442b-863f-9838ac70588d"
    },
    "status": "ok",
    "message": "Relativistic light Doppler / redshift",
    "success": true
}
```

#### `GET /v1/radial-velocity` — Velocity from a redshift

**Parameters:**
- `redshift` (query, optional, string) — Redshift z Example: `0.1`
- `observed_wavelength` (query, optional, string) — Or observed wavelength
- `rest_wavelength` (query, optional, string) — And rest wavelength

**Example:**
```bash
curl -H "x-oanor-key: $KEY" \
  "https://api.oanor.com/doppler-api/v1/radial-velocity?redshift=0.1"
```

**Response:**
```json
{
    "data": {
        "note": "Positive z (red-shift) means receding; negative (blue-shift) means approaching.",
        "formula": "β = ((1+z)² − 1) / ((1+z)² + 1); v = β·c. Non-relativistic: v ≈ z·c.",
        "direction": "receding",
        "redshift_z": 0.1,
        "velocity_m_s": 28487066.14,
        "velocity_km_s": 28487.0661,
        "velocity_fraction_c": 0.09502262,
        "non_relativistic_estimate_km_s": 29979.2458
    },
    "meta": {
        "timestamp": "2026-06-04T10:18:56.440Z",
        "request_id": "cfab36cd-b52e-4404-bf50-c77ecbeabca8"
    },
    "status": "ok",
    "message": "Velocity from a redshift",
    "success": true
}
```

#### `GET /v1/sound` — Acoustic Doppler shift

**Parameters:**
- `frequency` (query, required, string) — Emitted frequency (Hz) Example: `1000`
- `source_velocity` (query, optional, string) — Source velocity, + toward observer (m/s) Example: `30`
- `observer_velocity` (query, optional, string) — Observer velocity, + toward source (m/s)
- `sound_speed` (query, optional, string) — Speed of sound (m/s)
- `temperature` (query, optional, string) — Or air temperature (°C) to derive it Example: `20`

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

**Response:**
```json
{
    "data": {
        "formula": "f' = f·(v + vo) / (v − vs); positive velocities mean approaching.",
        "shifted": "higher (approaching)",
        "sound_speed_m_s": 343.2146,
        "frequency_shift_hz": 95.780969,
        "sound_speed_source": "air at 20°C",
        "source_velocity_m_s": 30,
        "emitted_frequency_hz": 1000,
        "observed_frequency_hz": 1095.780969,
        "observer_velocity_m_s": 0
    },
    "meta": {
        "timestamp": "2026-06-04T10:18:56.543Z",
        "request_id": "b5bdef9f-03fb-4526-9e55-e52a19ad69af"
    },
    "status": "ok",
    "message": "Acoustic Doppler shift",
    "success": true
}
```

### Meta

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

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

**Response:**
```json
{
    "data": {
        "api": "doppler",
        "note": "Doppler-effect maths (acoustic + relativistic) — computed locally and deterministically, no key, no third-party service.",
        "endpoints": [
            "/v1/sound",
            "/v1/light",
            "/v1/radial-velocity",
            "/v1/meta"
        ],
        "speed_of_light_m_s": 299792458,
        "default_sound_speed_m_s": 343
    },
    "meta": {
        "timestamp": "2026-06-04T10:18:56.624Z",
        "request_id": "0acc23e4-6bde-41c8-b5be-2c4c8fc2ef56"
    },
    "status": "ok",
    "message": "Meta",
    "success": true
}
```


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