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.
- Base URL
https://tempocito.com/api/v1/,GETwith query parameters orPOSTwith a JSON body. - OpenAPI 3.1 document:
/api/openapi.json. - MCP server (streamable HTTP, no session):
https://tempocito.com/api/mcp, server card at/.well-known/mcp/server-card.json. - Limit: 60 requests per minute per IP. Errors come back as
400witherror,messageanddocs. - Nothing is logged: requests are not stored.
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'.
distancerequiredstring- 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.
timerequiredstring- 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.
distancerequiredstring- 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.
timerequiredstring- 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_kmhoptionalnumber- vVO2max in km/h, from a field test (half Cooper: meters in 6 minutes ÷ 100).
distanceoptionalstring- 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.
timeoptionalstring- 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.
agerequirednumber- Age in years (10 to 90).
resting_hroptionalnumber- Resting heart rate in bpm (30 to 110), for Karvonen zones.
max_hroptionalnumber- 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.
distancerequiredstring- Goal race: 5k, 10k, half or marathon.
goal_timerequiredstring- Goal finish time: h:mm:ss or mm:ss (also 1h30, 90min, or seconds).
sessions_per_weekoptionalnumber- Runs per week: 3 or 4 for 5K and 10K, 3 to 6 for half and marathon. Default 3.
weeksoptionalnumber- Plan length in weeks: 6-12 (5K), 4-12 (10K), 8-20 (half), 12-24 (marathon). Default 8, 8, 12, 16.
ageoptionalnumber- Age in years (10 to 90): from 40, more recovery between hard sessions.
vo2maxoptionalnumber- Measured VO2max in ml/kg/min (20 to 90), to set the paces from it.
previous_timeoptionalstring- Your latest time on the same distance: h:mm:ss or mm:ss (also 1h30, 90min, or seconds).
unitoptionalstring- 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"
}
}
}