# Vibration & Natural Frequency API
> Single-degree-of-freedom vibration (spring-mass-damper) maths as an API, computed locally and deterministically. The natural endpoint gives the undamped natural frequency of a spring-mass system, ωn = √(k/m), fn = ωn/2π and the period T = 1/fn, and solves for whichever of the stiffness, mass or natural frequency you leave out. The damped endpoint analyses a damped system from the stiffness, mass and either a damping coefficient or a damping ratio: it returns the critical damping coefficient cc = 2√(km), the damping ratio ζ = c/cc, the classification (underdamped, critically damped or overdamped), and — for an underdamped system — the damped natural frequency ωd = ωn·√(1−ζ²), its period, and the logarithmic decrement δ = 2πζ/√(1−ζ²). The pendulum endpoint gives the period and frequency of a simple pendulum, T = 2π·√(L/g), and solves the length from a target period, with gravity adjustable. Everything is computed locally and deterministically, so it is instant and private. Ideal for mechanical, structural and earthquake-engineering tools, machine-condition-monitoring and isolation-design apps, instrument and clock design, and physics education. Pure local computation — no key, no third-party service, instant. Live, nothing stored. 3 endpoints. This is discrete spring-mass-damper vibration; for standing waves on strings and in air columns use a standing-wave 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/vibration-api/..."
```

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

## Endpoints

### Vibration

#### `GET /v1/damped` — Damped vibration & damping ratio

**Parameters:**
- `stiffness` (query, required, string) — Spring stiffness k (N/m) Example: `1000`
- `mass` (query, required, string) — Mass m (kg) Example: `2`
- `damping_coefficient` (query, optional, string) — Damping coefficient c (N·s/m) Example: `20`
- `damping_ratio` (query, optional, string) — Or damping ratio ζ directly

**Example:**
```bash
curl -H "x-oanor-key: $KEY" \
  "https://api.oanor.com/vibration-api/v1/damped?stiffness=1000&mass=2&damping_coefficient=20"
```

**Response:**
```json
{
    "data": {
        "formula": "ζ = c/(2√(km)); ωd = ωn√(1−ζ²); δ = 2πζ/√(1−ζ²).",
        "mass_kg": 2,
        "damping_ratio": 0.2236068,
        "stiffness_n_m": 1000,
        "classification": "underdamped",
        "damped_period_s": 0.288292,
        "damping_coefficient": 20,
        "logarithmic_decrement": 1.441462,
        "damped_natural_frequency_hz": 3.468702,
        "critical_damping_coefficient": 89.442719,
        "undamped_natural_frequency_hz": 3.558813,
        "damped_natural_frequency_rad_s": 21.794495,
        "undamped_natural_frequency_rad_s": 22.36068
    },
    "meta": {
        "timestamp": "2026-06-04T10:18:49.559Z",
        "request_id": "f8c73c15-a0ff-4350-929e-78d63c491e60"
    },
    "status": "ok",
    "message": "Damped vibration",
    "success": true
}
```

#### `GET /v1/natural` — Undamped natural frequency

**Parameters:**
- `stiffness` (query, optional, string) — Spring stiffness k (N/m) Example: `1000`
- `mass` (query, optional, string) — Mass m (kg) Example: `2`
- `natural_frequency` (query, optional, string) — Or natural frequency (Hz) to solve k/m

**Example:**
```bash
curl -H "x-oanor-key: $KEY" \
  "https://api.oanor.com/vibration-api/v1/natural?stiffness=1000&mass=2"
```

**Response:**
```json
{
    "data": {
        "formula": "ωn = √(k/m); fn = ωn/2π; T = 1/fn.",
        "mass_kg": 2,
        "period_s": 0.280993,
        "frequency_hz": 3.558813,
        "stiffness_n_m": 1000,
        "angular_frequency_rad_s": 22.36068
    },
    "meta": {
        "timestamp": "2026-06-04T10:18:49.636Z",
        "request_id": "c5f4a1e5-1fc3-466c-bed1-24d8df157700"
    },
    "status": "ok",
    "message": "Natural frequency",
    "success": true
}
```

#### `GET /v1/pendulum` — Simple pendulum period

**Parameters:**
- `length` (query, optional, string) — Pendulum length L (m) Example: `1`
- `period` (query, optional, string) — Or period (s) to solve length
- `gravity` (query, optional, string) — Gravity (default 9.80665)

**Example:**
```bash
curl -H "x-oanor-key: $KEY" \
  "https://api.oanor.com/vibration-api/v1/pendulum?length=1"
```

**Response:**
```json
{
    "data": {
        "formula": "T = 2π·√(L/g); ωn = √(g/L); valid for small swings.",
        "length_m": 1,
        "period_s": 2.006409,
        "gravity_ms2": 9.80665,
        "frequency_hz": 0.498403,
        "angular_frequency_rad_s": 3.131557
    },
    "meta": {
        "timestamp": "2026-06-04T10:18:49.743Z",
        "request_id": "d1c176ff-4a73-4acf-b6e3-a31862023735"
    },
    "status": "ok",
    "message": "Simple pendulum",
    "success": true
}
```

### Meta

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

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

**Response:**
```json
{
    "data": {
        "api": "vibration",
        "note": "Spring-mass-damper (SDOF) vibration — computed locally and deterministically, no key, no third-party service.",
        "endpoints": [
            "/v1/natural",
            "/v1/damped",
            "/v1/pendulum",
            "/v1/meta"
        ],
        "gravity_default_ms2": 9.80665
    },
    "meta": {
        "timestamp": "2026-06-04T10:18:49.843Z",
        "request_id": "ec80d3b3-30bf-4a20-8e09-a417d9f4d891"
    },
    "status": "ok",
    "message": "Meta",
    "success": true
}
```


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