# Spur Gear API
> Spur-gear geometry as an API, computed locally and deterministically for standard full-depth involute teeth. The geometry endpoint takes a module and a number of teeth (and an optional pressure angle, default 20°) and returns the complete tooth geometry: the pitch diameter (module × teeth), the base, tip (outside) and root diameters, the addendum, dedendum, whole and working depth, the circular and base pitch, the diametral pitch and the tooth thickness — all in millimetres. The module can be given directly or derived from a diametral pitch or a circular pitch. The pair endpoint meshes two gears of the same module and returns each gear's pitch and tip diameter, the centre distance (module × (z1 + z2) ÷ 2) and the gear ratio. The module endpoint converts freely between module, diametral pitch and circular pitch, or derives the module from a pitch diameter and tooth count. Everything is computed locally and deterministically, so it is instant and private. Ideal for machine-design and CAD tools, gear and gearbox calculators, maker, robotics and 3D-printing projects, and mechanical-engineering apps. Pure local computation — no key, no third-party service, instant. Live, nothing stored. 3 endpoints. This is spur-gear geometry; for bicycle gear ratios and development use a bike-gear API and for belt-and-pulley drives use a belt-drive 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/spurgear-api/..."
```

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

## Endpoints

### Gear

#### `GET /v1/geometry` — Single spur-gear geometry

**Parameters:**
- `module` (query, optional, string) — Module in mm Example: `2`
- `diametral_pitch` (query, optional, string) — Or diametral pitch (1/in)
- `circular_pitch` (query, optional, string) — Or circular pitch (mm)
- `teeth` (query, required, string) — Number of teeth (z) Example: `20`
- `pressure_angle` (query, optional, string) — Pressure angle deg (default 20) Example: `20`

**Example:**
```bash
curl -H "x-oanor-key: $KEY" \
  "https://api.oanor.com/spurgear-api/v1/geometry?module=2&teeth=20&pressure_angle=20"
```

**Response:**
```json
{
    "data": {
        "note": "Standard full-depth involute gear. Pitch dia = module × teeth; tip = m(z+2); root = m(z−2.5); base = pitch × cos(pressure angle).",
        "teeth": 20,
        "module_mm": 2,
        "addendum_mm": 2,
        "dedendum_mm": 2.5,
        "base_pitch_mm": 5.90426,
        "module_source": "module",
        "whole_depth_mm": 4.5,
        "tip_diameter_mm": 44,
        "base_diameter_mm": 37.5877,
        "root_diameter_mm": 35,
        "working_depth_mm": 4,
        "circular_pitch_mm": 6.28319,
        "pitch_diameter_mm": 40,
        "pressure_angle_deg": 20,
        "tooth_thickness_mm": 3.14159,
        "diametral_pitch_per_in": 12.7
    },
    "meta": {
        "timestamp": "2026-06-04T01:59:06.507Z",
        "request_id": "f4fe4625-5ec0-4546-916c-60a8cd669636"
    },
    "status": "ok",
    "message": "Single spur-gear geometry",
    "success": true
}
```

#### `GET /v1/module` — Module / DP / circular pitch

**Parameters:**
- `module` (query, optional, string) — Module (mm)
- `diametral_pitch` (query, optional, string) — Diametral pitch Example: `8`
- `circular_pitch` (query, optional, string) — Circular pitch (mm)
- `pitch_diameter` (query, optional, string) — Or pitch diameter (with teeth)
- `teeth` (query, optional, string) — Teeth (with pitch_diameter)

**Example:**
```bash
curl -H "x-oanor-key: $KEY" \
  "https://api.oanor.com/spurgear-api/v1/module?diametral_pitch=8"
```

**Response:**
```json
{
    "data": {
        "note": "module(mm) = 25.4 / diametral_pitch = circular_pitch / π = pitch_diameter / teeth.",
        "module_mm": 3.175,
        "circular_pitch_in": 0.392699,
        "circular_pitch_mm": 9.97456,
        "diametral_pitch_per_in": 8
    },
    "meta": {
        "timestamp": "2026-06-04T01:59:06.615Z",
        "request_id": "dcfb7222-bce3-4617-aca4-03319c2b9e0f"
    },
    "status": "ok",
    "message": "Module / DP / circular pitch",
    "success": true
}
```

#### `GET /v1/pair` — Meshing gear pair

**Parameters:**
- `module` (query, optional, string) — Module in mm Example: `2`
- `diametral_pitch` (query, optional, string) — Or diametral pitch
- `teeth_1` (query, required, string) — Pinion teeth (z1) Example: `20`
- `teeth_2` (query, required, string) — Gear teeth (z2) Example: `40`
- `pressure_angle` (query, optional, string) — Pressure angle deg Example: `20`

**Example:**
```bash
curl -H "x-oanor-key: $KEY" \
  "https://api.oanor.com/spurgear-api/v1/pair?module=2&teeth_1=20&teeth_2=40&pressure_angle=20"
```

**Response:**
```json
{
    "data": {
        "gear": {
            "teeth": 40,
            "tip_diameter_mm": 84,
            "pitch_diameter_mm": 80
        },
        "note": "Centre distance = module × (z1 + z2) / 2. Gear ratio = driven teeth ÷ driver teeth.",
        "pinion": {
            "teeth": 20,
            "tip_diameter_mm": 44,
            "pitch_diameter_mm": 40
        },
        "module_mm": 2,
        "gear_ratio": 2,
        "ratio_label": "40:20",
        "center_distance_mm": 60,
        "pressure_angle_deg": 20
    },
    "meta": {
        "timestamp": "2026-06-04T01:59:06.715Z",
        "request_id": "0aeb1fac-1a59-499d-9deb-c20d440154f2"
    },
    "status": "ok",
    "message": "Meshing gear pair",
    "success": true
}
```

### Meta

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

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

**Response:**
```json
{
    "data": {
        "api": "spurgear",
        "note": "Spur-gear geometry — computed locally and deterministically, no key, no third-party service.",
        "defaults": {
            "tooth_system": "full-depth involute",
            "pressure_angle_deg": 20
        },
        "endpoints": [
            "/v1/geometry",
            "/v1/pair",
            "/v1/module",
            "/v1/meta"
        ]
    },
    "meta": {
        "timestamp": "2026-06-04T01:59:06.809Z",
        "request_id": "ad4e62a0-5a12-4ee5-a2f8-38b0772ec97d"
    },
    "status": "ok",
    "message": "Meta",
    "success": true
}
```


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