# Running Pace API
> A running-pace calculator as an API. Work out pace and speed from a distance and a time (pace per kilometre and per mile, plus km/h, mph and m/s); compute the finish time from a distance and a target pace; predict your time at another distance using Peter Riegel's formula (T2 = T1 × (D2/D1)^1.06) — e.g. estimate a half-marathon from a 10K; and generate a split-time table for even pacing. Times accept seconds, M:SS or H:MM:SS. Perfect for running and fitness apps, race planning, training logs and pace bands. Pure local computation — no key, no third-party service, instant. Live, nothing stored. 5 endpoints. Distinct from general unit conversion and from body-metric (BMI/BMR) health calculators.

## 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/pace-api/..."
```

## Pricing
- **Free** (Free) — 1,035 calls/Mo, 2 req/s
- **Starter** ($1/Mo) — 8,750 calls/Mo, 8 req/s
- **Pro** ($21/Mo) — 138,500 calls/Mo, 20 req/s
- **Mega** ($59/Mo) — 730,000 calls/Mo, 50 req/s

## Endpoints

### Pace

#### `GET /v1/pace` — Pace + speed from distance & time

**Parameters:**
- `distance` (query, required, string) — Distance Example: `10`
- `distance_unit` (query, optional, string) — m|km|mi (default km) Example: `km`
- `time` (query, required, string) — seconds, M:SS or H:MM:SS Example: `50:00`

**Example:**
```bash
curl -H "x-oanor-key: $KEY" \
  "https://api.oanor.com/pace-api/v1/pace?distance=10&distance_unit=km&time=50%3A00"
```

**Response:**
```json
{
    "data": {
        "speed_ms": 3.333,
        "speed_kmh": 12,
        "speed_mph": 7.456,
        "pace_per_km": "5:00",
        "time_seconds": 3000,
        "pace_per_mile": "8:03",
        "distance_meters": 10000,
        "pace_per_km_seconds": 300,
        "pace_per_mile_seconds": 482.803
    },
    "meta": {
        "timestamp": "2026-06-03T01:09:44.556Z",
        "request_id": "b88bae07-cea4-417b-9e37-308de921ec83"
    },
    "status": "ok",
    "message": "Pace + speed from distance & time",
    "success": true
}
```

#### `GET /v1/predict` — Predict a race time (Riegel)

**Parameters:**
- `distance1` (query, required, string) — Known distance Example: `10`
- `time1` (query, required, string) — Known time Example: `50:00`
- `distance2` (query, required, string) — Target distance Example: `21.0975`
- `distance_unit` (query, optional, string) — m|km|mi (default km) Example: `km`

**Example:**
```bash
curl -H "x-oanor-key: $KEY" \
  "https://api.oanor.com/pace-api/v1/predict?distance1=10&time1=50%3A00&distance2=21.0975&distance_unit=km"
```

**Response:**
```json
{
    "data": {
        "to": {
            "distance_meters": 21097.5
        },
        "from": {
            "time": "50:00",
            "distance_meters": 10000
        },
        "formula": "Riegel (exponent 1.06)",
        "predicted_time": "1:50:19.2",
        "predicted_pace_per_km": "5:14",
        "predicted_time_seconds": 6619.209
    },
    "meta": {
        "timestamp": "2026-06-03T01:09:44.648Z",
        "request_id": "31d03910-a25b-453e-b6a1-9660c1fff529"
    },
    "status": "ok",
    "message": "Predict a race time",
    "success": true
}
```

#### `GET /v1/splits` — Split-time table

**Parameters:**
- `distance` (query, required, string) — Distance Example: `21.0975`
- `distance_unit` (query, optional, string) — m|km|mi (default km) Example: `km`
- `time` (query, required, string) — Total time Example: `1:45:00`
- `split` (query, optional, string) — km|mi (default km) Example: `km`

**Example:**
```bash
curl -H "x-oanor-key: $KEY" \
  "https://api.oanor.com/pace-api/v1/splits?distance=21.0975&distance_unit=km&time=1%3A45%3A00&split=km"
```

**Response:**
```json
{
    "data": {
        "splits": [
            {
                "split": 1,
                "distance": 1,
                "cumulative_time": "4:58.6"
            },
            {
                "split": 2,
                "distance": 2,
                "cumulative_time": "9:57.2"
            },
            {
                "split": 3,
                "distance": 3,
                "cumulative_time": "14:55.8"
            },
            {
                "split": 4,
                "distance": 4,
                "cumulative_time": "19:54.5"
            },
            {
                "split": 5,
                "distance": 5,
                "cumulative_time": "24:53.1"
            },
            {
                "split": 6,
                "distance": 6,
                "cumulative_time": "29:51.7"
            },
            {
                "split": 7,
                "distance": 7,
                "cumulative_time": "34:50.3"
            },
            {
                "split": 8,
                "distance": 8,
                "cumulative_time": "39:48.9"
            },
            {
                "split": 9,
                "distance": 9,
                "cumulative_time": "44:47.5"
            },
            {
                "split": 10,
                "distance": 10,
                "cumulative_time": "49:46.1"
            },
            {
                "split": 11,
                "distance": 11,
                "cumulative_time": "54:44.7"
            },
…(truncated, see openapi.json for full schema)
```

#### `GET /v1/time` — Finish time from distance & pace

**Parameters:**
- `distance` (query, required, string) — Distance Example: `10`
- `distance_unit` (query, optional, string) — m|km|mi (default km) Example: `km`
- `pace` (query, required, string) — Pace (e.g. 5:00) Example: `5:00`
- `pace_unit` (query, optional, string) — per_km|per_mile Example: `per_km`

**Example:**
```bash
curl -H "x-oanor-key: $KEY" \
  "https://api.oanor.com/pace-api/v1/time?distance=10&distance_unit=km&pace=5%3A00&pace_unit=per_km"
```

**Response:**
```json
{
    "data": {
        "pace": "5:00",
        "time": "50:00",
        "pace_unit": "per_km",
        "time_seconds": 3000,
        "distance_meters": 10000
    },
    "meta": {
        "timestamp": "2026-06-03T01:09:44.824Z",
        "request_id": "a64aa323-46af-4db1-ae5c-d12d88f3a485"
    },
    "status": "ok",
    "message": "Finish time from distance & pace",
    "success": true
}
```

### Meta

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

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

**Response:**
```json
{
    "data": {
        "name": "Running Pace API",
        "notes": "Race prediction uses Peter Riegel's T2 = T1 × (D2/D1)^1.06; treat it as an estimate. Nothing is stored.",
        "version": "v1",
        "endpoints": [
            {
                "path": "/v1/pace",
                "params": {
                    "time": "seconds, M:SS or H:MM:SS (required)",
                    "distance": "required",
                    "distance_unit": "m|km|mi (default km)"
                },
                "returns": "pace per km/mile and speed in km/h, mph, m/s"
            },
            {
                "path": "/v1/time",
                "params": {
                    "pace": "e.g. 5:00 (required)",
                    "distance": "required",
                    "pace_unit": "per_km|per_mile",
                    "distance_unit": "default km"
                },
                "returns": "the finish time"
            },
            {
                "path": "/v1/predict",
                "params": {
                    "time1": "required",
                    "distance1": "required",
                    "distance2": "required",
                    "distance_unit": "default km"
                },
                "returns": "predicted time at distance2 (Riegel)"
            },
            {
                "path": "/v1/splits",
                "params": {
                    "time": "required",
                    "split": "km|mi",
                    "distance": "required",
…(truncated, see openapi.json for full schema)
```


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