# Bicycle Gear API
> Bicycle gearing maths as an API, computed locally and deterministically. The gear endpoint takes a chainring and cog tooth count and a wheel size and returns every common gearing metric: the gear ratio, gear inches (the classic measure — ratio times wheel diameter in inches), the gain ratio (Sheldon Brown's crank-length-aware measure), the development or rollout (metres travelled per crank revolution), and the road speed at a chosen cadence in km/h and mph. The speed endpoint converts between a gear-and-cadence and road speed in either direction — the speed at a cadence, or the cadence needed for a target speed. The table endpoint builds a gear chart: give one or more chainrings and a cassette of cogs and it returns a matrix of gear inches, development, gain ratio or ratio for every combination — ideal for visualising a drivetrain. Wheel size can be a preset (700x25c, 26-inch, 29er and more) or an exact rolling circumference in millimetres, and crank length is configurable for the gain ratio. Everything is computed locally and deterministically, so it is instant and private. Ideal for cycling apps and bike-fit tools, drivetrain and gear-ratio planners, and bike-shop and component sites. Pure local computation — no key, no third-party service, instant. Live, nothing stored. 3 endpoints. This is bicycle gearing; for cycling power, FTP and training zones use a cycling 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/bikegear-api/..."
```

## Pricing
- **Free** (Free) — 10,935 calls/Mo, 2 req/s
- **Starter** ($12/Mo) — 20,550 calls/Mo, 8 req/s
- **Pro** ($32/Mo) — 255,500 calls/Mo, 20 req/s
- **Mega** ($70/Mo) — 1,320,000 calls/Mo, 50 req/s

## Endpoints

### Gearing

#### `GET /v1/gear` — Gearing metrics + speed

**Parameters:**
- `chainring` (query, required, string) — Chainring teeth Example: `50`
- `cog` (query, required, string) — Cog/sprocket teeth Example: `14`
- `wheel` (query, optional, string) — 700x25c|26|29er|… (or circumference) Example: `700x25c`
- `wheel_circumference_mm` (query, optional, string) — Exact rolling circumference
- `crank_length` (query, optional, string) — mm (default 170) Example: `170`
- `cadence` (query, optional, string) — rpm (default 90) Example: `90`

**Example:**
```bash
curl -H "x-oanor-key: $KEY" \
  "https://api.oanor.com/bikegear-api/v1/gear?chainring=50&cog=14&wheel=700x25c&crank_length=170&cadence=90"
```

**Response:**
```json
{
    "data": {
        "note": "Gear inches = ratio × wheel diameter (in). Development = distance per crank revolution. Gain ratio (Sheldon Brown) uses crank length.",
        "input": {
            "cog": 14,
            "chainring": 50,
            "cadence_rpm": 90,
            "crank_length_mm": 170,
            "wheel_circumference_mm": 2105
        },
        "ratio": 3.5714,
        "gain_ratio": 7.038,
        "gear_inches": 94.21,
        "development_m": 7.5179,
        "speed_at_cadence_kmh": 40.6,
        "speed_at_cadence_mph": 25.23
    },
    "meta": {
        "timestamp": "2026-06-04T01:59:19.299Z",
        "request_id": "97ed41fe-a8e1-415e-a5fe-6fd571eb2db6"
    },
    "status": "ok",
    "message": "Gearing metrics",
    "success": true
}
```

#### `GET /v1/speed` — Speed from cadence (or inverse)

**Parameters:**
- `chainring` (query, required, string) — Chainring teeth Example: `50`
- `cog` (query, required, string) — Cog teeth Example: `14`
- `wheel` (query, optional, string) — Wheel size Example: `700x25c`
- `cadence` (query, optional, string) — rpm (for speed) Example: `90`
- `speed_kmh` (query, optional, string) — Or target speed (for cadence)

**Example:**
```bash
curl -H "x-oanor-key: $KEY" \
  "https://api.oanor.com/bikegear-api/v1/speed?chainring=50&cog=14&wheel=700x25c&cadence=90"
```

**Response:**
```json
{
    "data": {
        "note": "Speed = development × cadence.",
        "input": {
            "cog": 14,
            "chainring": 50,
            "cadence_rpm": 90,
            "development_m": 7.5179
        },
        "speed_kmh": 40.6,
        "speed_mph": 25.23
    },
    "meta": {
        "timestamp": "2026-06-04T01:59:19.391Z",
        "request_id": "b03371bb-8eb3-4c6b-b683-acbf57f9399f"
    },
    "status": "ok",
    "message": "Speed / cadence",
    "success": true
}
```

#### `GET /v1/table` — Gear table for a cassette

**Parameters:**
- `chainrings` (query, required, string) — Chainring teeth, comma list Example: `50,34`
- `cogs` (query, required, string) — Cassette cogs, comma list Example: `11,13,15,17,19,21,24,28`
- `wheel` (query, optional, string) — Wheel size Example: `700x25c`
- `metric` (query, optional, string) — gear_inches|development|gain|ratio Example: `gear_inches`

**Example:**
```bash
curl -H "x-oanor-key: $KEY" \
  "https://api.oanor.com/bikegear-api/v1/table?chainrings=50%2C34&cogs=11%2C13%2C15%2C17%2C19%2C21%2C24%2C28&wheel=700x25c&metric=gear_inches"
```

**Response:**
```json
{
    "data": {
        "note": "Matrix of the chosen metric for each chainring × cog. metric = gear_inches (default), development, gain or ratio.",
        "input": {
            "cogs": [
                11,
                13,
                15,
                17,
                19,
                21,
                24,
                28
            ],
            "metric": "gear_inches",
            "chainrings": [
                50,
                34
            ],
            "wheel_circumference_mm": 2105
        },
        "table": [
            {
                "gears": [
                    {
                        "cog": 11,
                        "value": 119.91
                    },
                    {
                        "cog": 13,
                        "value": 101.46
                    },
                    {
                        "cog": 15,
                        "value": 87.93
                    },
                    {
                        "cog": 17,
                        "value": 77.59
                    },
                    {
                        "cog": 19,
                        "value": 69.42
                    },
                    {
                        "cog": 21,
                        "value": 62.81
                    },
                    {
                        "cog": 24,
                        "value": 54.96
                    },
                    {
                        "cog": 28,
          
…(truncated, see openapi.json for full schema)
```

### Meta

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

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

**Response:**
```json
{
    "data": {
        "note": "Wheel sizes are rolling circumferences in mm; pass wheel_circumference_mm for an exact value.",
        "wheels": [
            "20",
            "24",
            "26",
            "700x23c",
            "700x25c",
            "700x28c",
            "700x32c",
            "700x35c",
            "700c",
            "650b",
            "27.5x2.0",
            "26x1.5",
            "26x2.0",
            "29er",
            "29x2.2",
            "27x1.25"
        ],
        "service": "bikegear",
        "endpoints": {
            "/v1/gear": "All gearing metrics for a chainring/cog/wheel, including speed at a cadence.",
            "/v1/speed": "Speed from a gear and cadence, or the cadence for a target speed.",
            "/v1/table": "Gear table (gear inches / development / gain / ratio) for chainrings × a cassette."
        },
        "description": "Bicycle gearing maths: ratio, gear inches, gain ratio, development and speed at cadence, plus a gear table."
    },
    "meta": {
        "timestamp": "2026-06-04T01:59:19.586Z",
        "request_id": "304ff358-a6fb-44de-b490-45cb714cfabc"
    },
    "status": "ok",
    "message": "Meta",
    "success": true
}
```


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