# Highway Horizontal Curve API
> Horizontal road-curve geometry as an API, computed locally and deterministically — the curve-element, stationing and design-radius numbers a highway engineer, surveyor or civil-design tool lays out a road or railway curve with. The geometry endpoint takes the radius and the intersection (deflection) angle and returns the full simple circular curve: the tangent T = R·tan(Δ/2), the curve length L = R·Δ in radians, the long chord LC = 2R·sin(Δ/2), the middle ordinate M = R(1−cos(Δ/2)) and the external distance E = R(sec(Δ/2)−1), plus the degree of curve (arc definition) = 5729.578 ÷ R, the US shorthand for sharpness. The stations endpoint lays the curve out from the PI: the PC (point of curvature) = PI − tangent and the PT (point of tangency) = PC + curve length — and it reminds you the PT is reached along the arc, not by adding the tangent again. The min-radius endpoint gives the minimum radius for a design speed (AASHTO) R = V² ÷ (15·(e + f)), where e is the superelevation and f the side-friction factor, the banking-plus-grip that holds a vehicle in the turn. Everything is computed locally and deterministically, so it is instant and private. Ideal for highway- and rail-design tools, surveying and civil-engineering utilities, and CAD/GIS road layout. Pure local computation — no key, no third-party service, instant. US units (ft, mph). 3 compute endpoints. For slope and grade use a slope API; for open-channel drainage a Manning 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/horizontalcurve-api/..."
```

## Pricing
- **Free** (Free) — 5,200 calls/Mo, 2 req/s
- **Starter** ($12/Mo) — 53,000 calls/Mo, 6 req/s
- **Pro** ($38/Mo) — 224,000 calls/Mo, 15 req/s
- **Mega** ($119/Mo) — 1,140,000 calls/Mo, 40 req/s

## Endpoints

### Curve

#### `GET /v1/geometry` — Curve elements from radius and angle

**Parameters:**
- `radius_ft` (query, required, string) — Curve radius (ft) Example: `500`
- `deflection_angle_deg` (query, required, string) — Intersection/deflection angle (deg) Example: `30`

**Example:**
```bash
curl -H "x-oanor-key: $KEY" \
  "https://api.oanor.com/horizontalcurve-api/v1/geometry?radius_ft=500&deflection_angle_deg=30"
```

**Response:**
```json
{
    "data": {
        "note": "A simple circular curve from the radius R and the intersection (deflection) angle Δ: tangent T = R·tan(Δ/2), curve length L = R·Δ (radians), long chord LC = 2R·sin(Δ/2), middle ordinate M = R(1−cos(Δ/2)) and external E = R(sec(Δ/2)−1). The degree of curve (arc definition) = 5729.578 ÷ R is the US highway shorthand for sharpness — a bigger radius is a flatter, faster curve.",
        "inputs": {
            "radius_ft": 500,
            "deflection_angle_deg": 30
        },
        "long_chord_ft": 258.819,
        "curve_length_ft": 261.799,
        "tangent_length_ft": 133.975,
        "middle_ordinate_ft": 17.037,
        "degree_of_curve_deg": 11.4592,
        "external_distance_ft": 17.638
    },
    "meta": {
        "timestamp": "2026-06-07T08:18:03.268Z",
        "request_id": "0177095d-f7d3-4f26-a37f-7b71e92db5e2"
    },
    "status": "ok",
    "message": "Curve geometry",
    "success": true
}
```

#### `GET /v1/min-radius` — Minimum radius for a design speed

**Parameters:**
- `design_speed_mph` (query, required, string) — Design speed (mph) Example: `60`
- `superelevation` (query, optional, string) — Superelevation e (ft/ft, default 0.08) Example: `0.08`
- `side_friction` (query, optional, string) — Side-friction factor f (default 0.12) Example: `0.12`

**Example:**
```bash
curl -H "x-oanor-key: $KEY" \
  "https://api.oanor.com/horizontalcurve-api/v1/min-radius?design_speed_mph=60&superelevation=0.08&side_friction=0.12"
```

**Response:**
```json
{
    "data": {
        "note": "The minimum curve radius for a design speed (AASHTO) R = V² ÷ (15·(e + f)), where e is the superelevation (road banking, up to ~0.08–0.12) and f the maximum side-friction factor the tyres can use (falls with speed, ~0.10–0.16). Banking and friction together hold the car in the turn against the centripetal demand — a sharper curve than this needs a slower speed or more bank. Metric form uses 127 instead of 15.",
        "inputs": {
            "side_friction": 0.12,
            "superelevation": 0.08,
            "design_speed_mph": 60
        },
        "min_radius_ft": 1200,
        "degree_of_curve_max_deg": 4.7746
    },
    "meta": {
        "timestamp": "2026-06-07T08:18:03.369Z",
        "request_id": "fb609266-77de-46eb-b620-ba03307d7e4e"
    },
    "status": "ok",
    "message": "Min radius",
    "success": true
}
```

#### `GET /v1/stations` — PC and PT stations from the PI

**Parameters:**
- `pi_station_ft` (query, required, string) — PI station (ft) Example: `1000`
- `radius_ft` (query, required, string) — Curve radius (ft) Example: `500`
- `deflection_angle_deg` (query, required, string) — Intersection/deflection angle (deg) Example: `30`

**Example:**
```bash
curl -H "x-oanor-key: $KEY" \
  "https://api.oanor.com/horizontalcurve-api/v1/stations?pi_station_ft=1000&radius_ft=500&deflection_angle_deg=30"
```

**Response:**
```json
{
    "data": {
        "note": "The curve is laid out from the PI (point of intersection of the two tangents): the PC (point of curvature, where the curve begins) = PI − tangent, and the PT (point of tangency, where it ends) = PC + curve length. Note the PT is NOT PI + tangent — you travel the longer arc, not the two straight tangents, so chaining station equations along a road must follow the curve length.",
        "inputs": {
            "radius_ft": 500,
            "pi_station_ft": 1000,
            "deflection_angle_deg": 30
        },
        "pc_station_ft": 866.025,
        "pt_station_ft": 1127.825,
        "curve_length_ft": 261.799,
        "tangent_length_ft": 133.975
    },
    "meta": {
        "timestamp": "2026-06-07T08:18:03.468Z",
        "request_id": "d1869c23-d0ad-40e1-ad91-5a172f232c87"
    },
    "status": "ok",
    "message": "Stations",
    "success": true
}
```

### Meta

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

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

**Response:**
```json
{
    "data": {
        "notes": "US units (ft, mph, deg). T = R·tan(Δ/2); L = R·Δ(rad); LC = 2R·sin(Δ/2); M = R(1−cos(Δ/2)); E = R(sec(Δ/2)−1); degree of curve = 5729.578/R; R_min = V²/(15(e+f)). For slope/grade conversion use a slope API; for open-channel flow a Manning API.",
        "service": "horizontalcurve-api",
        "endpoints": {
            "GET /v1/meta": "This document.",
            "GET /v1/geometry": "Tangent, length, chord, ordinates and degree of curve.",
            "GET /v1/stations": "PC and PT stations from the PI station.",
            "GET /v1/min-radius": "Minimum radius for a design speed (AASHTO)."
        },
        "description": "Horizontal road-curve geometry: curve elements from radius and angle, PC/PT stationing, and minimum radius for a design speed."
    },
    "meta": {
        "timestamp": "2026-06-07T08:18:03.575Z",
        "request_id": "bcd0cad0-2ae5-42a2-9c77-ff2d35e4c023"
    },
    "status": "ok",
    "message": "Meta",
    "success": true
}
```


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