# Boat Propeller API
> Boat-propeller maths as an API, computed locally and deterministically — the slip, RPM and pitch numbers that decide whether a boat hits its numbers or labours. The slip endpoint gives propeller slip from the pitch, the prop RPM and the actual boat speed: theoretical speed = pitch × prop RPM ÷ 1215, and slip = (theoretical − actual) ÷ theoretical — a 19-inch prop at 2000 RPM should make 31 knots in theory, so a real 26.6 knots is about 15 % slip, normal for a clean planing boat. The prop-rpm endpoint gives the propeller RPM from the engine RPM and the gear (reduction) ratio — a 2:1 gearbox spins the prop at half engine speed — and, with a pitch, the theoretical no-slip speed at that RPM. The pitch endpoint gives the pitch needed to reach a target speed at a prop RPM and expected slip, pitch = target × 1215 ÷ (prop RPM × (1 − slip)), so you can prop the boat to let the engine reach the top of its wide-open-throttle range instead of lugging. Everything is computed locally and deterministically, so it is instant and private. Ideal for boating and marine apps, repower and prop-shop tools, performance calculators, and seamanship study aids. Pure local computation — no key, no third-party service, instant. Live, nothing stored. 3 compute endpoints. Estimates — hull, load and bottom condition shift real slip.

## 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/propeller-api/..."
```

## Pricing
- **Free** (Free) — 540 calls/Mo, 2 req/s
- **Starter** ($5/Mo) — 14,200 calls/Mo, 6 req/s
- **Pro** ($17/Mo) — 88,000 calls/Mo, 15 req/s
- **Mega** ($50/Mo) — 275,000 calls/Mo, 36 req/s

## Endpoints

### Propeller

#### `GET /v1/pitch` — Pitch for a target speed

**Parameters:**
- `target_speed_knots` (query, required, string) — Target speed in knots Example: `30`
- `prop_rpm` (query, required, string) — Propeller RPM Example: `2000`
- `slip_pct` (query, optional, string) — Expected slip % (default 12) Example: `12`

**Example:**
```bash
curl -H "x-oanor-key: $KEY" \
  "https://api.oanor.com/propeller-api/v1/pitch?target_speed_knots=30&prop_rpm=2000&slip_pct=12"
```

**Response:**
```json
{
    "data": {
        "note": "Required pitch = target speed × 1215 ÷ (prop RPM × (1 − slip)). More pitch is more speed per rev but loads the engine like a higher gear — too much and the engine can't reach its rated RPM. Tune pitch so the engine hits the top of its wide-open-throttle range; a 1-inch change shifts WOT RPM by roughly 150–200.",
        "inputs": {
            "prop_rpm": 2000,
            "slip_pct": 12,
            "target_speed_knots": 30
        },
        "required_pitch_in": 20.7
    },
    "meta": {
        "timestamp": "2026-06-06T23:54:01.490Z",
        "request_id": "6d53b3e3-0dcc-4688-b315-f4cfb4daa73d"
    },
    "status": "ok",
    "message": "Required pitch",
    "success": true
}
```

#### `GET /v1/prop-rpm` — Prop RPM from engine RPM

**Parameters:**
- `engine_rpm` (query, required, string) — Engine RPM Example: `4000`
- `gear_ratio` (query, required, string) — Gear (reduction) ratio Example: `2`
- `pitch_in` (query, optional, string) — Pitch in inches (for theoretical speed) Example: `19`

**Example:**
```bash
curl -H "x-oanor-key: $KEY" \
  "https://api.oanor.com/propeller-api/v1/prop-rpm?engine_rpm=4000&gear_ratio=2&pitch_in=19"
```

**Response:**
```json
{
    "data": {
        "note": "Prop RPM = engine RPM ÷ the gear (reduction) ratio — a 2:1 gearbox turns the prop at half engine speed, letting a big slow prop convert torque to thrust. Pass a pitch to also get the theoretical (no-slip) speed at that RPM.",
        "inputs": {
            "engine_rpm": 4000,
            "gear_ratio": 2
        },
        "prop_rpm": 2000,
        "theoretical_speed_knots": 31.27
    },
    "meta": {
        "timestamp": "2026-06-06T23:54:01.569Z",
        "request_id": "6a761c0a-4a2f-488c-aa2f-608d86abcd50"
    },
    "status": "ok",
    "message": "Prop RPM",
    "success": true
}
```

#### `GET /v1/slip` — Propeller slip

**Parameters:**
- `pitch_in` (query, required, string) — Propeller pitch in inches Example: `19`
- `prop_rpm` (query, required, string) — Propeller RPM Example: `2000`
- `actual_speed_knots` (query, required, string) — Actual boat speed in knots Example: `26.6`

**Example:**
```bash
curl -H "x-oanor-key: $KEY" \
  "https://api.oanor.com/propeller-api/v1/slip?pitch_in=19&prop_rpm=2000&actual_speed_knots=26.6"
```

**Response:**
```json
{
    "data": {
        "note": "Slip = (theoretical − actual speed) ÷ theoretical, where theoretical speed = pitch × prop RPM ÷ 1215. Slip is not loss — a prop must slip to make thrust. A clean planing boat runs ~10–15 %, a heavy displacement hull or a tug far more. Way more slip than that means an over-pitched prop, a fouled bottom or a slipping clutch.",
        "inputs": {
            "pitch_in": 19,
            "prop_rpm": 2000,
            "actual_speed_knots": 26.6
        },
        "slip_pct": 14.9,
        "theoretical_speed_knots": 31.27
    },
    "meta": {
        "timestamp": "2026-06-06T23:54:01.635Z",
        "request_id": "924926c6-3230-4a30-ba79-20ab78a3673d"
    },
    "status": "ok",
    "message": "Propeller slip",
    "success": true
}
```

### Meta

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

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

**Response:**
```json
{
    "data": {
        "notes": "US units (inches, RPM, knots). Theoretical speed = pitch × prop RPM ÷ 1215; slip = (theo − actual)/theo; prop RPM = engine RPM ÷ gear ratio. Estimates — hull, load and bottom condition all shift real slip.",
        "service": "propeller-api",
        "endpoints": {
            "GET /v1/meta": "This document.",
            "GET /v1/slip": "Propeller slip from pitch, prop RPM and actual speed.",
            "GET /v1/pitch": "Pitch needed to reach a target speed at a prop RPM and slip.",
            "GET /v1/prop-rpm": "Prop RPM from engine RPM and gear ratio (and theoretical speed)."
        },
        "description": "Boat-propeller maths: propeller slip, prop RPM from engine RPM and gear ratio, and the pitch needed for a target speed."
    },
    "meta": {
        "timestamp": "2026-06-06T23:54:01.712Z",
        "request_id": "fe01951a-fd28-4fc6-af00-7b0d38a0e7ed"
    },
    "status": "ok",
    "message": "Meta",
    "success": true
}
```


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