# Slider-Crank Mechanism API
> Slider-crank (piston-crank) mechanism kinematics as an API, computed locally and deterministically. The position endpoint takes the crank radius, the connecting-rod length and the crank angle from top dead centre and returns the exact piston displacement from TDC, x = r(1−cosθ) + l(1 − √(1−λ²sin²θ)) with λ = r/l, the piston-pin distance from the crank axis, the connecting-rod swing angle φ = asin(λ·sinθ), the stroke (2r), the rod ratio n = l/r and the fraction of stroke travelled. The velocity endpoint adds the crank speed (as rpm or angular velocity) and returns the exact piston velocity, v = ω·[r·sinθ + r·λ·sinθcosθ/√(1−λ²sin²θ)], and the piston acceleration from the standard two-term approximation a ≈ r·ω²·(cosθ + λ·cos2θ) — the inertia term engine designers use for balancing. The geometry endpoint summarises the whole mechanism: the stroke, the rod ratio, the top- and bottom-dead-centre positions, the maximum connecting-rod angle asin(λ), and — with a speed — the mean piston speed 2·stroke·(rev/s). Everything is computed locally and deterministically, so it is instant and private. Ideal for engine, compressor and pump-mechanism design tools, robotics and linkage simulation, CNC and animation, and mechanical-engineering education. Pure local computation — no key, no third-party service, instant. Live, nothing stored. 3 endpoints. This is slider-crank linkage kinematics; for rotational energy use a flywheel API and for shaft torsion use a torsion 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/crankslider-api/..."
```

## Pricing
- **Free** (Free) — 2,000 calls/Mo, 2 req/s
- **Starter** ($9/Mo) — 25,000 calls/Mo, 5 req/s
- **Pro** ($24/Mo) — 150,000 calls/Mo, 15 req/s
- **Mega** ($74/Mo) — 750,000 calls/Mo, 40 req/s

## Endpoints

### Slider-Crank

#### `GET /v1/geometry` — Mechanism geometry

**Parameters:**
- `crank_radius` (query, required, string) — Crank radius r (m) Example: `0.05`
- `rod_length` (query, required, string) — Connecting-rod length l (m) Example: `0.2`
- `rpm` (query, optional, string) — Crank speed (rpm) for mean speed Example: `3000`
- `angular_velocity` (query, optional, string) — Or angular velocity (rad/s)

**Example:**
```bash
curl -H "x-oanor-key: $KEY" \
  "https://api.oanor.com/crankslider-api/v1/geometry?crank_radius=0.05&rod_length=0.2&rpm=3000"
```

**Response:**
```json
{
    "data": {
        "rpm": 3000,
        "note": "Stroke = 2·crank_radius. Mean piston speed = 2·stroke·(rev/s). Larger rod ratio n = less secondary (obliquity) motion.",
        "inputs": {
            "rod_length": 0.2,
            "crank_radius": 0.05
        },
        "stroke": 0.1,
        "rod_ratio_n": 4,
        "angular_velocity": 314.159265,
        "obliquity_lambda": 0.25,
        "max_rod_angle_deg": 14.477512,
        "mean_piston_speed": 10,
        "bdc_distance_from_crank_axis": 0.15,
        "tdc_distance_from_crank_axis": 0.25
    },
    "meta": {
        "timestamp": "2026-06-04T10:18:36.071Z",
        "request_id": "0c06a569-0730-4922-9784-1819f8d632bb"
    },
    "status": "ok",
    "message": "Mechanism geometry",
    "success": true
}
```

#### `GET /v1/position` — Piston position

**Parameters:**
- `crank_radius` (query, required, string) — Crank radius r (m) Example: `0.05`
- `rod_length` (query, required, string) — Connecting-rod length l (m) Example: `0.2`
- `angle` (query, required, string) — Crank angle from TDC (degrees) Example: `90`

**Example:**
```bash
curl -H "x-oanor-key: $KEY" \
  "https://api.oanor.com/crankslider-api/v1/position?crank_radius=0.05&rod_length=0.2&angle=90"
```

**Response:**
```json
{
    "data": {
        "note": "Displacement measured from top dead centre (θ=0). Distance-from-crank-axis is the piston-pin to crank-centre length.",
        "inputs": {
            "angle_deg": 90,
            "rod_length": 0.2,
            "crank_radius": 0.05
        },
        "stroke": 0.1,
        "rod_ratio_n": 4,
        "rod_angle_deg": 14.477512,
        "obliquity_lambda": 0.25,
        "fraction_of_stroke": 0.563508,
        "displacement_from_tdc": 0.056351,
        "distance_from_crank_axis": 0.193649
    },
    "meta": {
        "timestamp": "2026-06-04T10:18:36.176Z",
        "request_id": "50076448-d2ba-4492-83ba-43c9be36ca9f"
    },
    "status": "ok",
    "message": "Piston position",
    "success": true
}
```

#### `GET /v1/velocity` — Piston velocity & acceleration

**Parameters:**
- `crank_radius` (query, required, string) — Crank radius r (m) Example: `0.05`
- `rod_length` (query, required, string) — Connecting-rod length l (m) Example: `0.2`
- `angle` (query, required, string) — Crank angle from TDC (degrees) Example: `90`
- `rpm` (query, optional, string) — Crank speed (rpm) Example: `3000`
- `angular_velocity` (query, optional, string) — Or angular velocity (rad/s)

**Example:**
```bash
curl -H "x-oanor-key: $KEY" \
  "https://api.oanor.com/crankslider-api/v1/velocity?crank_radius=0.05&rod_length=0.2&angle=90&rpm=3000"
```

**Response:**
```json
{
    "data": {
        "inputs": {
            "angle_deg": 90,
            "rod_length": 0.2,
            "crank_radius": 0.05,
            "angular_velocity": 314.159265
        },
        "velocity_note": "Exact velocity v = ω·[r·sinθ + r·λ·sinθcosθ/√(1−λ²sin²θ)]; positive = moving from TDC toward BDC.",
        "piston_velocity": 15.707963,
        "acceleration_note": "Standard 2-term approximation a ≈ r·ω²·(cosθ + λ·cos2θ).",
        "piston_acceleration": -1233.70055
    },
    "meta": {
        "timestamp": "2026-06-04T10:18:36.285Z",
        "request_id": "cb0f28fd-b127-495c-8d01-ac239f0bd678"
    },
    "status": "ok",
    "message": "Piston velocity & accel",
    "success": true
}
```

### Meta

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

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

**Response:**
```json
{
    "data": {
        "notes": "Lengths in metres, angle in degrees from top dead centre, speed as rpm or angular_velocity (rad/s). Acceleration is the standard two-term approximation.",
        "service": "crankslider-api",
        "formulae": {
            "stroke": "2·r,  max rod angle = asin(λ)",
            "velocity": "v = ω·[r·sinθ + r·λ·sinθcosθ/√(1−λ²sin²θ)]",
            "acceleration": "a ≈ r·ω²·(cosθ + λ·cos2θ)",
            "displacement": "x = r(1−cosθ) + l(1 − √(1−λ²sin²θ)),  λ = r/l"
        },
        "endpoints": {
            "GET /v1/meta": "This document.",
            "GET /v1/geometry": "Stroke, rod ratio, dead-centre positions, maximum rod angle and mean piston speed.",
            "GET /v1/position": "Piston displacement from TDC, distance from crank axis and connecting-rod angle at a crank angle.",
            "GET /v1/velocity": "Exact piston velocity and approximate acceleration at a crank angle for a given crank speed."
        },
        "description": "Slider-crank (piston-crank) mechanism kinematics: piston position, velocity, acceleration and mechanism geometry from crank radius, rod length and angle."
    },
    "meta": {
        "timestamp": "2026-06-04T10:18:36.383Z",
        "request_id": "cdb7b288-c7bc-42dc-a5b7-a68a23824ef1"
    },
    "status": "ok",
    "message": "Meta",
    "success": true
}
```


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