Nutrition Calculation
The nutrition calculation endpoint is Saturday’s core product. It takes an activity description and returns a personalized fuel prescription — carbohydrate, hydration, and electrolyte targets — with safety guardrails applied.
POST /v1/nutrition/calculate
Progressive enrichment
Saturday works with whatever data you have. More data produces more accurate prescriptions — but even minimal inputs return useful results.
The bare minimum for a calculation:
response = requests.post(
"https://api.saturday.fit/v1/nutrition/calculate",
headers={"Authorization": "Bearer sk_test_abc123def456"},
json={
"activity_type": "run",
"duration_min": 90,
"athlete_weight_kg": 70,
},
)
confidence_score. The numbers are based on population-level defaults for the given activity type and body weight.
Add intensity and environmental conditions for a meaningfully better prescription:
{
"activity_type": "bike",
"duration_min": 180,
"intensity_level": 7,
"athlete_weight_kg": 68,
"thermal_stress_level": 8
}
{
"activity_type": "bike",
"duration_min": 300,
"intensity_level": 8,
"is_race": true,
"athlete_id": "ath_abc123",
"thermal_stress_level": 7
}
athlete_id, Saturday pulls their stored profile — sweat level, saltiness, carb experience, fitness level, and past activity feedback. This is where prescriptions become genuinely personalized.
The enrichment path: Start with minimal inputs to get integrated fast, then progressively add more data as your integration matures. Every additional field improves accuracy.
Understanding the response
{
"tier": "full",
"carb_g_per_hr": 72,
"sodium_mg_per_hr": 800,
"fluid_ml_per_hr": 750,
"total_carb_g": 360,
"total_sodium_mg": 4000,
"total_fluid_ml": 3750,
"safety": {
"max_safe_fluid_ml_per_hr": 1500,
"max_safe_sodium_mg_per_hr": 3000,
"confidence_score": 0.85,
"requires_human_review": false,
"warnings": [
"High thermal stress. Consider ice, cold fluids, and shade."
],
"not_instructions": true
},
"attribution": {
"text": "Powered by Saturday",
"logo_url": "https://saturdaymorning.fit/logo.png",
"link": "https://saturdaymorning.fit",
"required": false
}
}
Confidence score
The safety.confidence_score (0.0-1.0) indicates how personalized the prescription is:
| Range | Meaning | Typical inputs |
|---|
| 0.8-1.0 | Strong personalization, athlete history | Athlete profile + conditions + feedback |
| 0.5-0.8 | Good estimates with some personalization | Weight + intensity + thermal stress |
| 0.0-0.5 | Population-level defaults applied | Minimal inputs (type + duration + weight) |
Comparing scenarios
Compare prescriptions across different conditions — ideal for race-day planning UIs:
POST /v1/nutrition/calculate/compare
{
"athlete_id": "ath_abc123",
"activity_type": "run",
"duration_min": 240,
"intensity_level": 8,
"is_race": true,
"scenarios": [
{
"label": "Cool morning",
"thermal_stress_level": 3
},
{
"label": "Hot afternoon",
"thermal_stress_level": 8
}
]
}
Teaser vs. full responses
Responses depend on the athlete’s Saturday subscription status:
- Subscribed athletes get exact numbers:
"carb_g_per_hr": 72
- Free/teaser athletes get ranges:
"carb_range_g_per_hr": "55-85"
See Freemium Model for implementation details.
Safety
Every calculation response includes a safety block. This is non-negotiable — Saturday is a nutrition API for athletes, and bad recommendations can cause real harm.
See Safety for the full guide on safety fields, risk levels, and display requirements.
Safety data is never gated behind subscription status. Even teaser responses include complete safety metadata.
Supported activity types
| Type | Key | Notes |
|---|
| Running | run | Road, trail, track |
| Cycling | bike | Road, gravel, mountain |
| Swimming | swim | Pool, open water |
| Rowing | row | On-water, ergometer |
| Skiing | ski | Cross-country, classic, skate |
| Hiking | hike | Long-duration, variable intensity |
| Weightlifting | lift | Strength training |
GET /v1/activity-types for the complete list with descriptions.
