# Railway Tractive Effort API
> Railway train-performance maths as an API, computed locally and deterministically — the tractive-effort, resistance and adhesion numbers a railway engineer, train planner or rail-sim developer rates motive power with. The tractive-effort endpoint gives the pulling force a locomotive develops = 375 × horsepower × efficiency ÷ speed (mph), the classic hyperbolic curve where a constant-power loco pulls hardest at low speed and tapers as it accelerates — 4,000 hp at 25 mph and 82 % efficiency is about 49,200 lbf at the rail. The resistance endpoint gives the forces a train fights: grade resistance ≈ 20 lb per ton per 1 % of grade (the weight component along the slope, the dominant force on a hill — a 5,000-ton train on a 1 % grade fights 100,000 lbf) plus curve resistance ≈ 0.8 lb per ton per degree of curve from flange friction. The adhesion endpoint gives the hard ceiling: however much power a loco has, it can only pull as hard as the wheels grip — maximum starting tractive effort = the adhesion coefficient (≈ 0.25 dry, more with sand) × the weight on the driving wheels, so 200 tons on the drivers is about 100,000 lbf before slip. Everything is computed locally and deterministically, so it is instant and private. Ideal for rail-operations and motive-power planning tools, train-simulator and railfan apps, and transport-engineering utilities. Pure local computation — no key, no third-party service, instant. Excludes the speed-dependent Davis rolling/air resistance. 3 compute endpoints. For highway curve geometry use a horizontal-curve 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/railway-api/..."
```

## Pricing
- **Free** (Free) — 4,750 calls/Mo, 2 req/s
- **Starter** ($13/Mo) — 49,500 calls/Mo, 6 req/s
- **Pro** ($41/Mo) — 211,000 calls/Mo, 15 req/s
- **Mega** ($126/Mo) — 1,115,000 calls/Mo, 40 req/s

## Endpoints

### Rail

#### `GET /v1/adhesion` — Adhesion-limited starting effort

**Parameters:**
- `weight_on_drivers_tons` (query, required, string) — Weight on driving wheels (tons) Example: `200`
- `adhesion_coefficient` (query, optional, string) — Adhesion coefficient (default 0.25) Example: `0.25`

**Example:**
```bash
curl -H "x-oanor-key: $KEY" \
  "https://api.oanor.com/railway-api/v1/adhesion?weight_on_drivers_tons=200&adhesion_coefficient=0.25"
```

**Response:**
```json
{
    "data": {
        "note": "However much power a locomotive has, it can only pull as hard as friction lets the wheels grip: the maximum starting tractive effort = the adhesion coefficient × the weight on the driving wheels. Dry steel-on-steel adhesion is ~0.25 (up to ~0.35–0.4 with sand and modern wheel-slip control), so 200 tons on the drivers gives about 100,000 lbf before the wheels spin. Heavier locomotives and sanders raise the ceiling.",
        "inputs": {
            "adhesion_coefficient": 0.25,
            "weight_on_drivers_tons": 200
        },
        "max_starting_tractive_effort_kn": 444.82,
        "max_starting_tractive_effort_lbf": 100000
    },
    "meta": {
        "timestamp": "2026-06-07T08:17:58.120Z",
        "request_id": "37ed67d0-ae47-4a5e-8995-ec3685d47ae8"
    },
    "status": "ok",
    "message": "Adhesion",
    "success": true
}
```

#### `GET /v1/resistance` — Grade and curve resistance

**Parameters:**
- `train_weight_tons` (query, required, string) — Train weight (tons) Example: `5000`
- `grade_pct` (query, optional, string) — Grade % (default 0) Example: `1`
- `curve_degrees` (query, optional, string) — Curve (degrees, default 0) Example: `2`

**Example:**
```bash
curl -H "x-oanor-key: $KEY" \
  "https://api.oanor.com/railway-api/v1/resistance?train_weight_tons=5000&grade_pct=1&curve_degrees=2"
```

**Response:**
```json
{
    "data": {
        "note": "Grade resistance is the dominant force on a hill: about 20 lb per ton per 1 % of grade (it is just the weight component along the slope), so a 5,000-ton train on a 1 % grade fights 100,000 lbf before it even rolls. Curve resistance adds roughly 0.8 lb per ton per degree of curve from wheel-flange friction. This excludes the speed-dependent rolling/air resistance (the Davis equation), which dominates on the flat at speed.",
        "inputs": {
            "grade_pct": 1,
            "curve_degrees": 2,
            "train_weight_tons": 5000
        },
        "curve_resistance_lbf": 8000,
        "grade_resistance_lbf": 100000,
        "total_resistance_lbf": 108000
    },
    "meta": {
        "timestamp": "2026-06-07T08:17:58.201Z",
        "request_id": "ff365eab-6c3d-44e9-abe2-2f1f144f5038"
    },
    "status": "ok",
    "message": "Resistance",
    "success": true
}
```

#### `GET /v1/tractive-effort` — Tractive effort from power and speed

**Parameters:**
- `power_hp` (query, required, string) — Locomotive power (hp) Example: `4000`
- `speed_mph` (query, required, string) — Speed (mph) Example: `25`
- `efficiency_pct` (query, optional, string) — Efficiency % (default 82) Example: `82`

**Example:**
```bash
curl -H "x-oanor-key: $KEY" \
  "https://api.oanor.com/railway-api/v1/tractive-effort?power_hp=4000&speed_mph=25&efficiency_pct=82"
```

**Response:**
```json
{
    "data": {
        "note": "Tractive effort at the rail = 375 × horsepower × efficiency ÷ speed (mph), so a constant-power locomotive pulls hardest at low speed and tapers as it speeds up — the classic hyperbolic TE curve. The 375 converts hp and mph into pounds of force, and the efficiency (~80–85 %) covers transmission and traction-motor losses. At very low speed this would run to infinity, so the real limit is adhesion (see /v1/adhesion).",
        "inputs": {
            "power_hp": 4000,
            "speed_mph": 25,
            "efficiency_pct": 82
        },
        "tractive_effort_kn": 218.85,
        "tractive_effort_lbf": 49200
    },
    "meta": {
        "timestamp": "2026-06-07T08:17:58.295Z",
        "request_id": "2e451b4a-1090-4fa8-b1e0-de6a1d44feb9"
    },
    "status": "ok",
    "message": "Tractive effort",
    "success": true
}
```

### Meta

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

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

**Response:**
```json
{
    "data": {
        "notes": "US units (hp, mph, tons, lbf). TE = 375·hp·eff/speed; grade resistance = 20·tons·grade%; curve = 0.8·tons·deg; adhesion TE = coeff·driver-weight. Excludes Davis rolling/air resistance. For highway curves use a horizontal-curve API.",
        "service": "railway-api",
        "endpoints": {
            "GET /v1/meta": "This document.",
            "GET /v1/adhesion": "Maximum starting tractive effort from adhesion.",
            "GET /v1/resistance": "Grade and curve resistance for a train.",
            "GET /v1/tractive-effort": "Tractive effort from power and speed."
        },
        "description": "Railway train-performance maths: tractive effort at speed, grade/curve resistance, and adhesion-limited starting effort."
    },
    "meta": {
        "timestamp": "2026-06-07T08:17:58.368Z",
        "request_id": "0c2a4931-2993-49fc-a656-98c2645be0a4"
    },
    "status": "ok",
    "message": "Meta",
    "success": true
}
```


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