Home› API

Running pace API and MCP server

Free JSON API for runners: the same formulas as the calculators on this site, answered in km and miles. No key, no sign-up, CORS open.

Pace, speed and splits

GET /api/v1/pace · MCP tool calculate_pace

Compute the running pace (per km and per mile), speed (km/h and mph) and split times for a distance and a finish time. Pace = time ÷ distance. Use it for 'what pace do I need for a 3:30 marathon' or 'how fast is 25:00 for 5K'.

distance requiredstring
Race distance: a race name (5k, 10k, half, marathon) or a number with its unit (10km, 6.2mi, 400m). A bare number is read as km.
time requiredstring
Finish time: h:mm:ss or mm:ss (also 1h30, 90min, or seconds).

Example

curl "https://tempocito.com/api/v1/pace?distance=marathon&time=3%3A30%3A00"
{
  "distance_km": 42.195,
  "distance_mi": 26.2188,
  "time": "3:30:00",
  "pace_per_km": "4:59",
  "pace_per_mile": "8:01",
  "speed_kmh": 12.06,
  "speed_mph": 7.49,
  "splits_km": [
    {
      "at": "km 5",
      "time": "24:53"
    },
    {
      "at": "km 10",
      "time": "49:46"
    },
    {
      "at": "km 15",
      "time": "1:14:39"
    },
    {
      "at": "km 20",
      "time": "1:39:32"
    },
    {
      "at": "km 25",
      "time": "2:04:25"
    },
    {
      "at": "km 30",
      "time": "2:29:18"
    },
    {
      "at": "km 35",
      "time": "2:54:11"
    },
    {
      "at": "km 40",
      "time": "3:19:05"
    },
    {
      "at": "Finish",
      "time": "3:30:00"
    }
  ],
  "splits_mile": [
    {
      "at": "Mile 5",
      "time": "40:03"
    },
    {
      "at": "Mile 10",
      "time": "1:20:06"
    },
    {
      "at": "Mile 15",
      "time": "2:00:09"
    },
    {
      "at": "Mile 20",
      "time": "2:40:11"
    },
    {
      "at": "Mile 25",
      "time": "3:20:14"
    },
    {
      "at": "Finish",
      "time": "3:30:00"
    }
  ],
  "formula": "pace = time ÷ distance; speed = distance ÷ time"
}

Race time predictions

GET /api/v1/predict · MCP tool predict_race_times

Predict 5K, 10K, half marathon and marathon times from one recent race result, with two models: Riegel (T2 = T1 × (D2/D1)^1.06) and Jack Daniels' VDOT. Predictions assume the training for the target distance is done; a marathon prediction from a 5K is optimistic without long runs.

distance requiredstring
Distance of the race you ran: a race name (5k, 10k, half, marathon) or a number with its unit (10km, 6.2mi, 400m). A bare number is read as km.
time requiredstring
Your time on it: h:mm:ss or mm:ss (also 1h30, 90min, or seconds).

Example

curl "https://tempocito.com/api/v1/predict?distance=10k&time=45%3A00"
{
  "from": {
    "distance_km": 10,
    "time": "45:00"
  },
  "vdot": 45.3,
  "predictions": [
    {
      "race": "5K",
      "distance_km": 5,
      "riegel": "21:35",
      "riegel_pace_per_km": "4:19",
      "riegel_pace_per_mile": "6:57",
      "daniels": "21:42"
    },
    {
      "race": "10K",
      "distance_km": 10,
      "riegel": "45:00",
      "riegel_pace_per_km": "4:30",
      "riegel_pace_per_mile": "7:15",
      "daniels": "45:00"
    },
    {
      "race": "Half marathon",
      "distance_km": 21.0975,
      "riegel": "1:39:17",
      "riegel_pace_per_km": "4:42",
      "riegel_pace_per_mile": "7:34",
      "daniels": "1:39:44"
    },
    {
      "race": "Marathon",
      "distance_km": 42.195,
      "riegel": "3:27:01",
      "riegel_pace_per_km": "4:54",
      "riegel_pace_per_mile": "7:54",
      "daniels": "3:27:15"
    }
  ],
  "sources": [
    "Riegel, P. S. (1981), American Scientist 69(3)",
    "Daniels, J. and Gilbert, J. (1979), Oxygen Power"
  ]
}

Training paces from vVO2max

GET /api/v1/training-paces · MCP tool training_paces

Training paces (per km and per mile) for each intensity zone, as a percentage of vVO2max (maximal aerobic speed). Give vVO2max in km/h, or a recent race (distance and time) to estimate it with the Péronnet-Thibault endurance model.

vvo2max_kmh optionalnumber
vVO2max in km/h, from a field test (half Cooper: meters in 6 minutes ÷ 100).
distance optionalstring
Or: distance of a recent race: a race name (5k, 10k, half, marathon) or a number with its unit (10km, 6.2mi, 400m). A bare number is read as km.
time optionalstring
Or: your time on it: h:mm:ss or mm:ss (also 1h30, 90min, or seconds).

Example

curl "https://tempocito.com/api/v1/training-paces?vvo2max_kmh=16"
{
  "vvo2max_kmh": 16,
  "vvo2max_mph": 9.9,
  "vo2max_estimate": 56,
  "zones": [
    {
      "zone": "Recovery",
      "percent_vvo2max": "55-65",
      "pace_per_km": "5:46-6:49",
      "pace_per_mile": "9:17-10:58",
      "speed_kmh": "8.8-10.4"
    },
    {
      "zone": "Easy running, long run",
      "percent_vvo2max": "65-75",
      "pace_per_km": "5:00-5:46",
      "pace_per_mile": "8:03-9:17",
      "speed_kmh": "10.4-12"
    },
    {
      "zone": "Tempo, marathon pace",
      "percent_vvo2max": "75-85",
      "pace_per_km": "4:25-5:00",
      "pace_per_mile": "7:06-8:03",
      "speed_kmh": "12-13.6"
    },
    {
      "zone": "Threshold, 10K pace",
      "percent_vvo2max": "85-90",
      "pace_per_km": "4:10-4:25",
      "pace_per_mile": "6:42-7:06",
      "speed_kmh": "13.6-14.4"
    },
    {
      "zone": "Long intervals",
      "percent_vvo2max": "90-95",
      "pace_per_km": "3:57-4:10",
      "pace_per_mile": "6:21-6:42",
      "speed_kmh": "14.4-15.2"
    },
    {
      "zone": "vVO2max, short intervals",
      "percent_vvo2max": "95-105",
      "pace_per_km": "3:34-3:57",
      "pace_per_mile": "5:45-6:21",
      "speed_kmh": "15.2-16.8"
    }
  ],
  "formula": "pace = 3600 ÷ (vVO2max × %); VO2max ≈ vVO2max × 3.5"
}

Max heart rate and zones

GET /api/v1/heart-rate-zones · MCP tool heart_rate_zones

Estimate max heart rate from age (Tanaka 208 − 0.7 × age, Gellish, Fox 220 − age) and give the five training zones in bpm: as % of max HR, or with the Karvonen method when the resting heart rate is given. A measured max HR overrides the estimate.

age requirednumber
Age in years (10 to 90).
resting_hr optionalnumber
Resting heart rate in bpm (30 to 110), for Karvonen zones.
max_hr optionalnumber
Measured max heart rate in bpm (120 to 230), if known.

Example

curl "https://tempocito.com/api/v1/heart-rate-zones?age=35&resting_hr=55"
{
  "max_hr_estimates": {
    "tanaka": 184,
    "gellish": 183,
    "fox": 185
  },
  "max_hr_used": 184,
  "method": "Karvonen (heart rate reserve)",
  "zones": [
    {
      "zone": 1,
      "name": "Recovery",
      "percent": "50-60% of reserve",
      "bpm": "120-132"
    },
    {
      "zone": 2,
      "name": "Easy running",
      "percent": "60-70% of reserve",
      "bpm": "132-145"
    },
    {
      "zone": 3,
      "name": "Tempo, marathon pace",
      "percent": "70-80% of reserve",
      "bpm": "145-158"
    },
    {
      "zone": 4,
      "name": "Threshold, 10K pace",
      "percent": "80-90% of reserve",
      "bpm": "158-171"
    },
    {
      "zone": 5,
      "name": "vVO2max",
      "percent": "90-100% of reserve",
      "bpm": "171-184"
    }
  ],
  "sources": [
    "Tanaka, H. et al. (2001), JACC 37(1)",
    "Karvonen, M. J. et al. (1957), Ann Med Exp Biol Fenn 35(3)"
  ]
}

Training plan

GET /api/v1/plan · MCP tool training_plan

Week by week training plan for a 5K, 10K, half marathon or marathon goal time, the same plan as the site's plan page: phases (base, development, intensity, taper, race), each session with its pace. Paces come from the goal race pace, or from VO2max when given; age over 40 adds recovery, a previous time on the distance spreads the progression.

distance requiredstring
Goal race: 5k, 10k, half or marathon.
goal_time requiredstring
Goal finish time: h:mm:ss or mm:ss (also 1h30, 90min, or seconds).
sessions_per_week optionalnumber
Runs per week: 3 or 4 for 5K and 10K, 3 to 6 for half and marathon. Default 3.
weeks optionalnumber
Plan length in weeks: 6-12 (5K), 4-12 (10K), 8-20 (half), 12-24 (marathon). Default 8, 8, 12, 16.
age optionalnumber
Age in years (10 to 90): from 40, more recovery between hard sessions.
vo2max optionalnumber
Measured VO2max in ml/kg/min (20 to 90), to set the paces from it.
previous_time optionalstring
Your latest time on the same distance: h:mm:ss or mm:ss (also 1h30, 90min, or seconds).
unit optionalstring
Unit of the paces written in the sessions: km or mi. Default km.

Example

curl "https://tempocito.com/api/v1/plan?distance=half&goal_time=1%3A45%3A00"
{
  "race": "Half marathon",
  "goal_time": "1:45:00",
  "level": "Advanced",
  "total_weeks": 12,
  "sessions_per_week": 3,
  "paces": {
    "race": {
      "per_km": "4:59",
      "per_mile": "8:01"
    },
    "easy": {
      "per_km": "6:29",
      "per_mile": "10:25"
    },
    "tempo": {
      "per_km": "5:14",
      "per_mile": "8:25"
    },
    "intervals": {
      "per_km": "4:44",
      "per_mile": "7:36"
    },
    "long_run": {
      "per_km": "5:59",
      "per_mile": "9:37"
    }
  },
  "weeks": [
    {
      "week": 1,
      "phase": "Base",
      "sessions": [
        {
          "type": "easy",
          "title": "Easy run",
          "detail": "45 min at easy pace (6:29/km)"
        },
        {
          "type": "intervals",
          "title": "Short intervals",
          "detail": "10×400 m at 4:44/km, 1:30 jog recovery"
        },
        {
          "type": "long_run",
          "title": "Long run",
          "detail": "80 min at easy pace (6:29/km)"
        }
      ]
    },
    "… 11 more weeks"
  ],
  "page": "https://tempocito.com/training-plan"
}

Use it from an AI assistant (MCP)

The 5 endpoints are also MCP tools: calculate_pace, predict_race_times, training_paces, heart_rate_zones, training_plan. Add the server to a client that supports remote MCP servers:

{
  "mcpServers": {
    "tempocito": {
      "type": "http",
      "url": "https://tempocito.com/api/mcp"
    }
  }
}