# Gear Ratio API
> Gear-train ratio, speed and torque maths as an API, computed locally and deterministically. The ratio endpoint computes the gear ratio of a single pair from the driver and driven tooth counts (or pitch diameters), ratio = N_driven/N_driver, classifies it as a reduction (more torque, less speed) or an overdrive, and — given an input speed and torque — returns the output speed (input/ratio) and the output torque (input·ratio·efficiency). The train endpoint computes a compound gear train: the overall ratio is the product of the individual stage ratios, and it returns each stage ratio, the output speed and torque, noting that idler gears change only the direction of rotation, not the ratio. The solve endpoint finds the missing one of the input speed, the output speed and the ratio from the other two — for example, the ratio needed to drop a 1500 rpm motor to a 500 rpm output. Everything is computed locally and deterministically, so it is instant and private. Ideal for drivetrain, robotics and machine-design tools, gearbox and transmission selection, bicycle and vehicle gearing, and mechanical-engineering education. Pure local computation — no key, no third-party service, instant. Live, nothing stored. 3 endpoints. This is gear-train ratio and torque; for spur-gear tooth geometry use a spur-gear 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/gearratio-api/..."
```

## Pricing
- **Free** (Free) — 3,000 calls/Mo, 2 req/s
- **Starter** ($8/Mo) — 40,000 calls/Mo, 5 req/s
- **Pro** ($22/Mo) — 250,000 calls/Mo, 20 req/s
- **Mega** ($69/Mo) — 1,500,000 calls/Mo, 60 req/s

## Endpoints

### Gear

#### `GET /v1/ratio` — Single-pair gear ratio

**Parameters:**
- `driver_teeth` (query, optional, string) — Driver gear teeth Example: `20`
- `driven_teeth` (query, optional, string) — Driven gear teeth Example: `60`
- `driver_diameter` (query, optional, string) — Or driver pitch diameter
- `driven_diameter` (query, optional, string) — and driven pitch diameter
- `input_speed` (query, optional, string) — Input speed (rpm) Example: `1500`
- `input_torque` (query, optional, string) — Input torque Example: `10`
- `efficiency` (query, optional, string) — Efficiency (0–1, default 1) Example: `1`

**Example:**
```bash
curl -H "x-oanor-key: $KEY" \
  "https://api.oanor.com/gearratio-api/v1/ratio?driver_teeth=20&driven_teeth=60&input_speed=1500&input_torque=10&efficiency=1"
```

**Response:**
```json
{
    "data": {
        "note": "ratio = driven/driver. Output speed = input/ratio; output torque = input·ratio·efficiency.",
        "type": "reduction (torque up, speed down)",
        "inputs": {
            "driven_teeth": 60,
            "driver_teeth": 20
        },
        "gear_ratio": 3,
        "output_torque": 30,
        "output_speed_rpm": 500
    },
    "meta": {
        "timestamp": "2026-06-04T18:38:22.477Z",
        "request_id": "0cdb3c8b-2dd4-4253-abe2-d84f91e14b4d"
    },
    "status": "ok",
    "message": "Gear ratio",
    "success": true
}
```

#### `GET /v1/solve` — Solve speed / ratio

**Parameters:**
- `input_speed` (query, optional, string) — Input speed (rpm) Example: `1500`
- `output_speed` (query, optional, string) — Output speed (rpm) Example: `500`
- `ratio` (query, optional, string) — Gear ratio

**Example:**
```bash
curl -H "x-oanor-key: $KEY" \
  "https://api.oanor.com/gearratio-api/v1/solve?input_speed=1500&output_speed=500"
```

**Response:**
```json
{
    "data": {
        "mode": "solve_ratio",
        "note": "ratio = input_speed/output_speed.",
        "ratio": 3,
        "inputs": {
            "input_speed": 1500,
            "output_speed": 500
        }
    },
    "meta": {
        "timestamp": "2026-06-04T18:38:22.583Z",
        "request_id": "8724696a-76ac-4709-94ad-b8c406398a3d"
    },
    "status": "ok",
    "message": "Solve speed/ratio",
    "success": true
}
```

#### `GET /v1/train` — Compound train ratio

**Parameters:**
- `stages` (query, required, string) — JSON array of {driver, driven} Example: `[{"driver":20,"driven":60},{"driver":15,"driven":45}]`
- `input_speed` (query, optional, string) — Input speed (rpm) Example: `1800`
- `input_torque` (query, optional, string) — Input torque Example: `5`
- `efficiency` (query, optional, string) — Per-stage efficiency (0–1, default 1) Example: `1`

**Example:**
```bash
curl -H "x-oanor-key: $KEY" \
  "https://api.oanor.com/gearratio-api/v1/train?stages=%5B%7B%22driver%22%3A20%2C%22driven%22%3A60%7D%2C%7B%22driver%22%3A15%2C%22driven%22%3A45%7D%5D&input_speed=1800&input_torque=5&efficiency=1"
```

**Response:**
```json
{
    "data": {
        "note": "Overall ratio = product of stage (driven/driver) ratios. Idler gears change direction only, not the ratio.",
        "type": "reduction",
        "stages": [
            {
                "ratio": 3,
                "stage": 1,
                "driven": 60,
                "driver": 20
            },
            {
                "ratio": 3,
                "stage": 2,
                "driven": 45,
                "driver": 15
            }
        ],
        "stage_count": 2,
        "output_torque": 45,
        "overall_ratio": 9,
        "output_speed_rpm": 200
    },
    "meta": {
        "timestamp": "2026-06-04T18:38:22.665Z",
        "request_id": "6093e877-6f63-4386-bb24-d2089ed66acf"
    },
    "status": "ok",
    "message": "Compound train",
    "success": true
}
```

### Meta

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

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

**Response:**
```json
{
    "data": {
        "notes": "Teeth counts or diameters are unitless ratios; speed in rpm, torque in any consistent unit. A ratio > 1 is a reduction (more torque, less speed). Idler gears only reverse direction.",
        "service": "gearratio-api",
        "formulae": {
            "ratio": "ratio = N_driven/N_driver",
            "speed": "output = input/ratio",
            "train": "overall = Π(driven_i/driver_i)",
            "torque": "output = input·ratio·efficiency"
        },
        "endpoints": {
            "GET /v1/meta": "This document.",
            "GET /v1/ratio": "Gear ratio (from teeth or diameters) with output speed and torque.",
            "GET /v1/solve": "Solve the missing one of input speed, output speed and ratio.",
            "GET /v1/train": "Compound-train overall ratio from a list of stages, with output speed and torque."
        },
        "description": "Gear-train ratio calculator: single-pair ratio with speed and torque, compound-train overall ratio, and speed/ratio solving."
    },
    "meta": {
        "timestamp": "2026-06-04T18:38:22.764Z",
        "request_id": "1911ad03-0aff-4a22-8eeb-56f329b4382d"
    },
    "status": "ok",
    "message": "Meta",
    "success": true
}
```


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