# Banked Curve API
> Banked-curve and circular-motion dynamics as an API, computed locally and deterministically. The speed endpoint takes the radius of a curve and its banking (bank) angle and returns the frictionless ideal (design) speed at which the banking alone supplies the centripetal force, v = √(r·g·tanθ); give a coefficient of friction as well and it also returns the maximum safe speed before the vehicle slides outward up the bank, v = √(r·g·(tanθ+μ)/(1−μ·tanθ)), and the minimum speed before it slides inward down the bank — every speed in metres per second, km/h, mph and knots, plus the centripetal acceleration. The bank-angle endpoint inverts this: from a design speed and radius it returns the ideal banking angle θ = atan(v²/(r·g)) and the equivalent superelevation as a ratio and a percentage, the cant a road or railway needs so no side friction is used at that speed. The flat-curve endpoint handles an unbanked curve from the coefficient of friction: the maximum cornering speed v = √(μ·r·g) for a given radius and the minimum radius v²/(μ·g) for a given speed. Gravity defaults to standard 9.80665 m/s² and can be overridden. Everything is computed locally and deterministically, so it is instant and private. Ideal for road and racetrack design tools, vehicle-dynamics and driving-simulator apps, civil and transportation engineering, and physics education. Pure local computation — no key, no third-party service, instant. Live, nothing stored. 3 endpoints. This is curve banking and cornering dynamics; for projectile and SUVAT kinematics use a physics 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/bankedcurve-api/..."
```

## Pricing
- **Free** (Free) — 3,000 calls/Mo, 2 req/s
- **Starter** ($5/Mo) — 40,000 calls/Mo, 5 req/s
- **Pro** ($15/Mo) — 250,000 calls/Mo, 15 req/s
- **Mega** ($49/Mo) — 1,500,000 calls/Mo, 40 req/s

## Endpoints

### Banked Curve

#### `GET /v1/bank-angle` — Ideal banking angle for a design speed

**Parameters:**
- `radius` (query, required, string) — Curve radius (m) Example: `120`
- `speed` (query, optional, string) — Design speed (m/s) Example: `25`
- `speed_kmh` (query, optional, string) — Or design speed (km/h)
- `speed_mph` (query, optional, string) — Or design speed (mph)
- `gravity` (query, optional, string) — Gravity (default 9.80665)

**Example:**
```bash
curl -H "x-oanor-key: $KEY" \
  "https://api.oanor.com/bankedcurve-api/v1/bank-angle?radius=120&speed=25"
```

**Response:**
```json
{
    "data": {
        "note": "Frictionless ideal banking angle so no side friction is needed at the design speed.",
        "formula": "θ = atan(v²/(r·g)); superelevation e = tanθ = v²/(r·g).",
        "radius_m": 120,
        "gravity_ms2": 9.80665,
        "design_speed": {
            "speed_ms": 25,
            "speed_kmh": 90,
            "speed_mph": 55.923407,
            "speed_knots": 48.596112
        },
        "ideal_bank_angle_deg": 27.972869,
        "ideal_bank_angle_rad": 0.48821867,
        "superelevation_ratio": 0.53110219,
        "superelevation_percent": 53.110219,
        "centripetal_acceleration_ms2": 5.208333
    },
    "meta": {
        "timestamp": "2026-06-04T10:18:54.633Z",
        "request_id": "a5e9c7ee-5856-4e7b-ae21-b8832c94d90f"
    },
    "status": "ok",
    "message": "Ideal banking angle",
    "success": true
}
```

#### `GET /v1/flat-curve` — Unbanked curve speed & radius limits

**Parameters:**
- `friction` (query, required, string) — Coefficient of friction Example: `0.7`
- `radius` (query, optional, string) — Radius (m) for max speed Example: `80`
- `speed` (query, optional, string) — Or speed (m/s) for minimum radius
- `gravity` (query, optional, string) — Gravity (default 9.80665)

**Example:**
```bash
curl -H "x-oanor-key: $KEY" \
  "https://api.oanor.com/bankedcurve-api/v1/flat-curve?friction=0.7&radius=80"
```

**Response:**
```json
{
    "data": {
        "note": "Unbanked (flat) curve — friction alone supplies the centripetal force.",
        "formula": "flat curve: v_max = √(μ·r·g); minimum radius r_min = v²/(μ·g).",
        "radius_m": 80,
        "max_speed": {
            "note": "Above this the vehicle skids on the flat curve.",
            "speed_ms": 23.434428,
            "speed_kmh": 84.36394,
            "speed_mph": 52.421322,
            "speed_knots": 45.552883
        },
        "gravity_ms2": 9.80665,
        "friction_coefficient": 0.7,
        "max_centripetal_acceleration_ms2": 6.864655
    },
    "meta": {
        "timestamp": "2026-06-04T10:18:54.735Z",
        "request_id": "e215ad18-0ff9-4433-9f88-d0a5df513fdd"
    },
    "status": "ok",
    "message": "Unbanked curve limits",
    "success": true
}
```

#### `GET /v1/speed` — Safe speeds on a banked curve

**Parameters:**
- `radius` (query, required, string) — Curve radius (m) Example: `100`
- `bank_angle` (query, required, string) — Banking angle (degrees, 0–90) Example: `20`
- `friction` (query, optional, string) — Coefficient of friction (optional) Example: `0.3`
- `gravity` (query, optional, string) — Gravity (default 9.80665 m/s²)

**Example:**
```bash
curl -H "x-oanor-key: $KEY" \
  "https://api.oanor.com/bankedcurve-api/v1/speed?radius=100&bank_angle=20&friction=0.3"
```

**Response:**
```json
{
    "data": {
        "ideal": {
            "note": "Frictionless design speed: the banking alone supplies the centripetal force.",
            "speed_ms": 18.892667,
            "speed_kmh": 68.013602,
            "speed_mph": 42.261693,
            "speed_knots": 36.724407,
            "centripetal_acceleration_ms2": 3.569329
        },
        "formula": "v_ideal = √(r·g·tanθ); with friction μ: v_max = √(r·g·(tanθ+μ)/(1−μ·tanθ)).",
        "radius_m": 100,
        "max_speed": {
            "note": "Above this the vehicle slides outward (up the bank).",
            "speed_ms": 27.035995,
            "speed_kmh": 97.329583,
            "speed_mph": 60.477799,
            "speed_knots": 52.553771
        },
        "min_speed": {
            "note": "Below this the vehicle slides inward (down the bank).",
            "speed_ms": 7.52049,
            "speed_kmh": 27.073763,
            "speed_mph": 16.822857,
            "speed_knots": 14.618663
        },
        "gravity_ms2": 9.80665,
        "bank_angle_deg": 20,
        "friction_coefficient": 0.3
    },
    "meta": {
        "timestamp": "2026-06-04T10:18:54.838Z",
        "request_id": "3a913ba2-0589-4f10-a923-7d35fc3949e4"
    },
    "status": "ok",
    "message": "Safe speeds on a banked curve",
    "success": true
}
```

### Meta

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

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

**Response:**
```json
{
    "data": {
        "api": "banked-curve",
        "note": "Banked-curve and circular-motion dynamics — computed locally and deterministically, no key, no third-party service.",
        "endpoints": [
            "/v1/speed",
            "/v1/bank-angle",
            "/v1/flat-curve",
            "/v1/meta"
        ],
        "gravity_default_ms2": 9.80665
    },
    "meta": {
        "timestamp": "2026-06-04T10:18:54.928Z",
        "request_id": "83323086-52d1-4a01-ac8f-e4a1ec0a28c9"
    },
    "status": "ok",
    "message": "Meta",
    "success": true
}
```


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