# Hydraulic Cylinder API
> Hydraulic-cylinder engineering maths as an API, computed locally and deterministically — the force, speed and oil-volume numbers a fluid-power designer, machine builder or hydraulics technician sizes a cylinder with. The force endpoint gives the push and pull from the bore, rod diameter and working pressure: extending, the oil acts on the full bore area, so the cylinder is strongest pushing out; retracting, it acts only on the annulus left by the rod, giving less force — a 100 mm bore with a 56 mm rod at 160 bar pushes about 125.7 kN out but pulls only 86.3 kN back, which is why a press or an excavator does its hard work on the extend stroke. The speed endpoint gives the piston speed from the pump flow (speed = flow ÷ area), so extending is the slower stroke and retracting the faster, the trade-off every circuit designer balances against force. The volume endpoint gives the swept oil volume per stroke for extend and retract, the rod displacement and the bore-to-annulus area ratio — the differential (regeneration) ratio used to speed the extend stroke in a regen circuit — so the pump, tank and lines can be sized for the larger volume. Everything is computed locally and deterministically, so it is instant and private. Ideal for fluid-power and machine-design tools, hydraulics-sizing calculators, mobile- and industrial-equipment utilities, and engineering apps. Pure local computation — no key, no third-party service, instant. Ideal-area estimates — allow for friction, back-pressure and efficiency. 3 compute endpoints. For Pascal force-multiplication use a hydraulics API; for valve sizing a valve-flow (Cv/Kv) 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/hydrauliccylinder-api/..."
```

## Pricing
- **Free** (Free) — 5,100 calls/Mo, 2 req/s
- **Starter** ($12/Mo) — 54,000 calls/Mo, 6 req/s
- **Pro** ($39/Mo) — 229,000 calls/Mo, 15 req/s
- **Mega** ($118/Mo) — 1,170,000 calls/Mo, 40 req/s

## Endpoints

### Cylinder

#### `GET /v1/force` — Extend and retract force

**Parameters:**
- `bore_mm` (query, required, string) — Bore (piston) diameter (mm) Example: `100`
- `rod_mm` (query, required, string) — Rod diameter (mm) Example: `56`
- `pressure_bar` (query, required, string) — Working pressure (bar) Example: `160`

**Example:**
```bash
curl -H "x-oanor-key: $KEY" \
  "https://api.oanor.com/hydrauliccylinder-api/v1/force?bore_mm=100&rod_mm=56&pressure_bar=160"
```

**Response:**
```json
{
    "data": {
        "note": "Force = pressure × piston area. Extending, the oil pushes on the full bore area, so the cylinder is strongest pushing out; retracting, it acts only on the annulus left by the rod, giving less force. That is why a press or a digging machine does its hard work on the extend stroke. The same pressure on a bigger bore gives proportionally more force (area grows with the diameter squared).",
        "inputs": {
            "rod_mm": 56,
            "bore_mm": 100,
            "pressure_bar": 160
        },
        "bore_area_mm2": 7854,
        "extend_force_kn": 125.66,
        "annulus_area_mm2": 5391,
        "retract_force_kn": 86.26
    },
    "meta": {
        "timestamp": "2026-06-06T23:53:53.137Z",
        "request_id": "4c0ea757-b3ab-4fd0-b751-876514bf3ab7"
    },
    "status": "ok",
    "message": "Cylinder force",
    "success": true
}
```

#### `GET /v1/speed` — Piston speed from flow

**Parameters:**
- `bore_mm` (query, required, string) — Bore diameter (mm) Example: `100`
- `rod_mm` (query, required, string) — Rod diameter (mm) Example: `56`
- `flow_lpm` (query, required, string) — Oil flow (L/min) Example: `30`

**Example:**
```bash
curl -H "x-oanor-key: $KEY" \
  "https://api.oanor.com/hydrauliccylinder-api/v1/speed?bore_mm=100&rod_mm=56&flow_lpm=30"
```

**Response:**
```json
{
    "data": {
        "note": "Piston speed = oil flow ÷ piston area. Extending fills the full bore, so for a given pump flow the extend stroke is the slower one; retracting fills only the smaller annulus, so it moves faster (and needs a bigger flow path for the oil leaving the bore side). Speed and force trade off — the same flow and pressure give a fast light stroke or a slow strong one depending on the area.",
        "inputs": {
            "rod_mm": 56,
            "bore_mm": 100,
            "flow_lpm": 30
        },
        "extend_speed_mm_s": 63.7,
        "retract_speed_mm_s": 92.7
    },
    "meta": {
        "timestamp": "2026-06-06T23:53:53.233Z",
        "request_id": "8934722f-4d71-4aac-b1e4-10469578bab6"
    },
    "status": "ok",
    "message": "Piston speed",
    "success": true
}
```

#### `GET /v1/volume` — Swept volume per stroke

**Parameters:**
- `bore_mm` (query, required, string) — Bore diameter (mm) Example: `100`
- `rod_mm` (query, required, string) — Rod diameter (mm) Example: `56`
- `stroke_mm` (query, required, string) — Stroke length (mm) Example: `500`

**Example:**
```bash
curl -H "x-oanor-key: $KEY" \
  "https://api.oanor.com/hydrauliccylinder-api/v1/volume?bore_mm=100&rod_mm=56&stroke_mm=500"
```

**Response:**
```json
{
    "data": {
        "note": "The oil drawn to extend = full bore area × stroke; to retract = annulus area × stroke. The difference is the volume the rod takes up, and the bore-to-annulus area ratio is the cylinder's differential (regeneration) ratio — feeding the rod-side oil back to the bore in a regen circuit speeds the extend stroke at the cost of force. Size the pump and tank for the larger (extend) volume.",
        "inputs": {
            "rod_mm": 56,
            "bore_mm": 100,
            "stroke_mm": 500
        },
        "area_ratio": 1.457,
        "extend_volume_l": 3.927,
        "retract_volume_l": 2.695,
        "rod_displacement_l": 1.232
    },
    "meta": {
        "timestamp": "2026-06-06T23:53:53.330Z",
        "request_id": "520a3578-306a-4210-9e14-2209e26b75ef"
    },
    "status": "ok",
    "message": "Swept volume",
    "success": true
}
```

### Meta

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

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

**Response:**
```json
{
    "data": {
        "notes": "Metric (mm, bar, L/min, kN, mm/s, L). Force = P×area (bore for extend, annulus for retract); speed = flow÷area; volume = area×stroke. For Pascal force-multiplication use a hydraulics API; for valve sizing a valve-flow (Cv/Kv) API.",
        "service": "hydrauliccylinder-api",
        "endpoints": {
            "GET /v1/meta": "This document.",
            "GET /v1/force": "Extend (bore) and retract (annulus) force at a working pressure.",
            "GET /v1/speed": "Piston extend/retract speed from the pump flow.",
            "GET /v1/volume": "Swept volume per stroke and the differential area ratio."
        },
        "description": "Hydraulic-cylinder maths: extend/retract force from bore, rod and pressure; piston speed from oil flow; and swept volume per stroke."
    },
    "meta": {
        "timestamp": "2026-06-06T23:53:53.429Z",
        "request_id": "50c2cd5d-bd41-4f01-8a4d-26faccde17a2"
    },
    "status": "ok",
    "message": "Meta",
    "success": true
}
```


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