# Swimming API
> Swimming maths as an API, computed locally and deterministically — the SWOLF, threshold-pace and per-100 m numbers a swimmer, coach or training app works a set out with. The swolf endpoint scores stroke efficiency for one length: SWOLF (swim + golf) = the strokes taken plus the seconds taken, and like golf lower is better — gliding further per stroke or swimming faster both cut it, so a 25 m length in 18 strokes and 30 s is a SWOLF of 48. Because it is pool-length and stroke dependent, the score is normalized to 25 m so lengths in different pools compare. The css endpoint computes Critical Swim Speed, the swimmer's threshold pace, from two all-out time trials: CSS = (distance1 − distance2) ÷ (time1 − time2) — the classic 400 m and 200 m test, where 6:00 and 2:50 give about 1.05 m/s, a 1:35 / 100 m threshold; training paces are then set as offsets from CSS, the swimmer's equivalent of a runner's threshold or an erg's 2 k pace. The pace endpoint gives speed and the per-100 m pace swimmers actually quote (time ÷ distance × 100), so 100 m in 1:30 is a 1:30 / 100 m pace at 1.11 m/s. Everything is computed locally and deterministically, so it is instant and private. Ideal for swim-training and coaching tools, lap-tracker and triathlon apps, and fitness calculators. Pure local computation — no key, no third-party service, instant. 3 compute endpoints. For running pace use a pace API; for indoor rowing a rowing 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/swimming-api/..."
```

## Pricing
- **Free** (Free) — 7,200 calls/Mo, 2 req/s
- **Starter** ($7/Mo) — 60,500 calls/Mo, 6 req/s
- **Pro** ($24/Mo) — 247,000 calls/Mo, 15 req/s
- **Mega** ($76/Mo) — 1,160,000 calls/Mo, 40 req/s

## Endpoints

### Swimming

#### `GET /v1/css` — Critical Swim Speed

**Parameters:**
- `dist1_m` (query, required, string) — Longer trial distance (m) Example: `400`
- `time1_s` (query, required, string) — Longer trial time (s) Example: `360`
- `dist2_m` (query, required, string) — Shorter trial distance (m) Example: `200`
- `time2_s` (query, required, string) — Shorter trial time (s) Example: `170`

**Example:**
```bash
curl -H "x-oanor-key: $KEY" \
  "https://api.oanor.com/swimming-api/v1/css?dist1_m=400&time1_s=360&dist2_m=200&time2_s=170"
```

**Response:**
```json
{
    "data": {
        "note": "Critical Swim Speed is the swimmer's threshold pace — the speed they could in theory hold indefinitely — from two time trials: CSS = (distance1 − distance2) ÷ (time1 − time2). The classic test is a 400 m and a 200 m all-out; 400 m in 6:00 and 200 m in 2:50 gives about 1.05 m/s, a 1:35 / 100 m threshold pace. Training paces are then set as offsets from CSS, the swimmer's equivalent of a runner's threshold or an erg's 2 k pace.",
        "inputs": {
            "dist1_m": 400,
            "dist2_m": 200,
            "time1_s": 360,
            "time2_s": 170
        },
        "css_m_per_s": 1.0526,
        "css_pace_100m": "1:35.0",
        "css_pace_100m_s": 95
    },
    "meta": {
        "timestamp": "2026-06-07T08:17:52.214Z",
        "request_id": "1b491dc0-1aae-4d83-873f-f3bcef8458bd"
    },
    "status": "ok",
    "message": "Critical Swim Speed",
    "success": true
}
```

#### `GET /v1/pace` — Speed and pace per 100 m

**Parameters:**
- `distance_m` (query, required, string) — Distance swum (m) Example: `100`
- `time_seconds` (query, required, string) — Time (s) Example: `90`

**Example:**
```bash
curl -H "x-oanor-key: $KEY" \
  "https://api.oanor.com/swimming-api/v1/pace?distance_m=100&time_seconds=90"
```

**Response:**
```json
{
    "data": {
        "note": "Swim pace is quoted per 100 m, not per kilometre: pace/100 m = time ÷ distance × 100. 100 m in 1:30 is a 1:30 / 100 m pace at 1.11 m/s, and a 1500 m in 24:00 is a 1:36 pace. Per-100 m pace is the swimmer's common currency for sets and splits, and pairs with the SWOLF efficiency score and CSS threshold pace.",
        "inputs": {
            "distance_m": 100,
            "time_seconds": 90
        },
        "pace_100m": "1:30.0",
        "pace_100m_s": 90,
        "speed_m_per_s": 1.1111
    },
    "meta": {
        "timestamp": "2026-06-07T08:17:52.303Z",
        "request_id": "8a0de234-eebb-4217-baf1-a6248ec949ae"
    },
    "status": "ok",
    "message": "Swim pace",
    "success": true
}
```

#### `GET /v1/swolf` — SWOLF efficiency score

**Parameters:**
- `strokes` (query, required, string) — Strokes for the length Example: `18`
- `time_seconds` (query, required, string) — Time for the length (s) Example: `30`
- `pool_length_m` (query, optional, string) — Pool length (m, default 25) Example: `25`

**Example:**
```bash
curl -H "x-oanor-key: $KEY" \
  "https://api.oanor.com/swimming-api/v1/swolf?strokes=18&time_seconds=30&pool_length_m=25"
```

**Response:**
```json
{
    "data": {
        "note": "SWOLF (swim + golf) scores stroke efficiency for one length = the strokes taken plus the seconds taken. Like golf, lower is better: gliding further per stroke or swimming faster both cut the score. A 25 m length in 18 strokes and 30 s is a SWOLF of 48. Compare like with like — it is pool-length and stroke dependent — so the score is normalized to 25 m here; chase a lower SWOLF at the same speed to swim more efficiently, not just harder.",
        "swolf": 48,
        "inputs": {
            "strokes": 18,
            "time_seconds": 30,
            "pool_length_m": 25
        },
        "swolf_normalized_25m": 48
    },
    "meta": {
        "timestamp": "2026-06-07T08:17:52.371Z",
        "request_id": "71d5dadb-8bd6-4632-a154-90b78bb0374c"
    },
    "status": "ok",
    "message": "SWOLF",
    "success": true
}
```

### Meta

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

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

**Response:**
```json
{
    "data": {
        "notes": "Metres, seconds. SWOLF = strokes + time; CSS = (d1−d2)/(t1−t2); pace/100 = time/distance·100. For running pace use a pace API; for rowing a rowing API.",
        "service": "swimming-api",
        "endpoints": {
            "GET /v1/css": "Critical Swim Speed and threshold pace from two time trials.",
            "GET /v1/meta": "This document.",
            "GET /v1/pace": "Speed and pace per 100 m from a distance and time.",
            "GET /v1/swolf": "SWOLF score (strokes + seconds) for a length, normalized to 25 m."
        },
        "description": "Swimming maths: SWOLF efficiency score, Critical Swim Speed from a two-distance test, and swim pace per 100 m."
    },
    "meta": {
        "timestamp": "2026-06-07T08:17:52.462Z",
        "request_id": "565d1d19-d2b2-412b-978b-051073163556"
    },
    "status": "ok",
    "message": "Meta",
    "success": true
}
```


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