# Ship Stability API
> Ship initial-stability maths as an API, computed locally and deterministically — the metacentric-height, righting-moment and rolling-period numbers a naval architect, ship officer or marine-surveyor judges a vessel by. The metacentric-height endpoint gives GM = KM − KG, the single most important stability figure: the height of the metacentre (set by the hull form and draught) above the centre of gravity (set by how the ship is loaded), with a classification from a dangerous negative GM, through tender and comfortable, to a stiff GM that rolls violently — naval architects aim for the middle, because too little is unsafe and too much is hard on cargo and crew. The righting-moment endpoint gives the small-angle righting arm GZ ≈ GM · sin(heel) and the righting moment (GZ × displacement) that pushes the ship back upright, valid up to roughly 7–10° before the true GZ curve bends away. The roll-period endpoint gives the natural transverse rolling period T = 2π·k / √(g·GM) from the GM and beam — the same relation sailors run in reverse as the rolling-period test, where a suddenly longer roll warns that GM has dropped. Everything is computed locally and deterministically, so it is instant and private. Ideal for naval-architecture and ship-design tools, marine-surveyor and loading-software utilities, maritime-training apps and stability dashboards. Pure local computation — no key, no third-party service, instant. Initial-stability estimates — use full KN cross-curves for large angles. 3 compute endpoints. For hull speed and design ratios use a sailing 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/shipstability-api/..."
```

## Pricing
- **Free** (Free) — 4,500 calls/Mo, 2 req/s
- **Starter** ($14/Mo) — 49,000 calls/Mo, 6 req/s
- **Pro** ($42/Mo) — 213,000 calls/Mo, 15 req/s
- **Mega** ($129/Mo) — 1,130,000 calls/Mo, 40 req/s

## Endpoints

### Stability

#### `GET /v1/metacentric-height` — Metacentric height GM

**Parameters:**
- `km_m` (query, required, string) — Height of the metacentre above keel KM (m) Example: `8`
- `kg_m` (query, required, string) — Height of the centre of gravity above keel KG (m) Example: `7`

**Example:**
```bash
curl -H "x-oanor-key: $KEY" \
  "https://api.oanor.com/shipstability-api/v1/metacentric-height?km_m=8&kg_m=7"
```

**Response:**
```json
{
    "data": {
        "gm_m": 1,
        "note": "The metacentric height GM = KM − KG is the single most important initial-stability number: the height of the metacentre (set by the hull form and draught) above the centre of gravity (set by loading). Positive GM means the ship returns upright; negative GM means it lolls or capsizes. Too small is dangerous, but too large gives a violent, cargo-damaging roll — naval architects aim for a comfortable middle.",
        "inputs": {
            "kg_m": 7,
            "km_m": 8
        },
        "stability": "very stiff — violent roll, hard on cargo and crew"
    },
    "meta": {
        "timestamp": "2026-06-06T23:53:53.940Z",
        "request_id": "824989c6-77b0-466d-8c5e-4a097f8fe15b"
    },
    "status": "ok",
    "message": "Metacentric height",
    "success": true
}
```

#### `GET /v1/righting-moment` — Righting arm GZ and righting moment

**Parameters:**
- `gm_m` (query, required, string) — Metacentric height GM (m) Example: `1.0`
- `heel_deg` (query, required, string) — Heel angle (degrees) Example: `10`
- `displacement_t` (query, required, string) — Displacement (tonnes) Example: `5000`

**Example:**
```bash
curl -H "x-oanor-key: $KEY" \
  "https://api.oanor.com/shipstability-api/v1/righting-moment?gm_m=1.0&heel_deg=10&displacement_t=5000"
```

**Response:**
```json
{
    "data": {
        "note": "For small heel angles the righting arm GZ ≈ GM · sin(heel), and the righting moment that pushes the ship back upright = GZ × displacement. This linear relation holds up to roughly 7–10°; beyond that the true GZ curve bends away from it as the deck edge nears the water, so use a full cross-curve (KN) analysis for large angles. A bigger GM gives a steeper initial righting arm.",
        "inputs": {
            "gm_m": 1,
            "heel_deg": 10,
            "displacement_t": 5000
        },
        "righting_arm_gz_m": 0.1736,
        "righting_moment_t_m": 868.2,
        "righting_moment_kn_m": 8514.5
    },
    "meta": {
        "timestamp": "2026-06-06T23:53:54.026Z",
        "request_id": "4202dbb9-2713-4fb6-8d7f-cef349e613dc"
    },
    "status": "ok",
    "message": "Righting moment",
    "success": true
}
```

#### `GET /v1/roll-period` — Natural rolling period

**Parameters:**
- `gm_m` (query, required, string) — Metacentric height GM (m) Example: `1.0`
- `beam_m` (query, required, string) — Beam / breadth (m) Example: `15`
- `roll_gyration_factor` (query, optional, string) — Gyration factor k=c·B (default 0.35) Example: `0.35`

**Example:**
```bash
curl -H "x-oanor-key: $KEY" \
  "https://api.oanor.com/shipstability-api/v1/roll-period?gm_m=1.0&beam_m=15&roll_gyration_factor=0.35"
```

**Response:**
```json
{
    "data": {
        "note": "The natural rolling period T = 2π·k / √(g·GM), where k is the transverse radius of gyration (about 0.34–0.40 of the beam for a typical ship). A stiff ship (large GM) rolls fast with a short period; a tender ship rolls slowly. Sailors run this in reverse as the 'rolling-period test' — timing the roll to estimate GM — and a period that suddenly lengthens warns that GM has dropped dangerously.",
        "inputs": {
            "gm_m": 1,
            "beam_m": 15,
            "roll_gyration_factor": 0.35
        },
        "roll_period_s": 10.53,
        "radius_of_gyration_m": 5.25
    },
    "meta": {
        "timestamp": "2026-06-06T23:53:54.115Z",
        "request_id": "9c63a356-cfc1-46de-81d3-1a7a316396da"
    },
    "status": "ok",
    "message": "Roll period",
    "success": true
}
```

### Meta

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

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

**Response:**
```json
{
    "data": {
        "notes": "Metric (m, t, °, s). GM = KM − KG; GZ ≈ GM·sin(heel) (small angles ≤ ~10°); T = 2π·k/√(g·GM), k ≈ 0.35·beam. Initial-stability estimates — use full KN cross-curves for large angles. For hull speed and design ratios use a sailing API.",
        "service": "shipstability-api",
        "endpoints": {
            "GET /v1/meta": "This document.",
            "GET /v1/roll-period": "Natural transverse rolling period from GM and beam.",
            "GET /v1/righting-moment": "Small-angle righting arm GZ and righting moment.",
            "GET /v1/metacentric-height": "GM = KM − KG with a stability classification."
        },
        "description": "Ship initial-stability maths: metacentric height GM, the righting arm and moment at a heel angle, and the natural rolling period."
    },
    "meta": {
        "timestamp": "2026-06-06T23:53:54.201Z",
        "request_id": "f583980d-93ae-46fa-9d20-fdea7c230244"
    },
    "status": "ok",
    "message": "Meta",
    "success": true
}
```


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