{ "openapi": "3.1.1", "info": { "title": "Sports Travel-Fatigue Estimator API", "version": "1.0.0", "summary": "Travel distance, time-zone jumps, rest and back-to-backs per game as a fatigue score.", "description": "Every endpoint performs the same calculation as the human page and returns inputs, result, units, assumptions, sources, warnings and computedAt. MCP endpoint: /mcp." }, "servers": [ { "url": "https://sportstravelfatigueestimator.usefulweb.site" } ], "paths": { "/api/v1/calculate": { "post": { "operationId": "calculate", "summary": "Travel distance, time-zone jumps, rest and back-to-backs per game as a fatigue score.", "description": "Enter a team's schedule (date, city or coordinates). For every game the estimator computes the great-circle travel distance from the previous venue, the time-zone shift and its direction, rest days, back-to-backs and schedule density, and combines them into a 0–100 fatigue score with openly documented weights. It is a heuristic for comparing schedules, not a physiological measurement.\n\nMethodology:\n- Travel distance: great-circle (haversine) distance between the previous venue (or the starting city) and this venue, with a mean Earth radius of 6371 km. Real road or flight routes are longer.\n- Time-zone shift = UTC offset at the venue − UTC offset at the previous venue, on the game date (daylight saving time included via the IANA time-zone database). Positive = eastward (clocks ahead).\n- Fatigue score (0–100, heuristic): travel 1 point per 100 km (max 30); time zones: hours of shift not yet recovered × 5 (eastward) or × 3.5 (westward), max 25, assuming recovery of 1 h per full day between games eastward and 1.5 h westward; rest: same-day game 30, back-to-back (next day) 20, one rest day 8, two rest days 3; density: 5 points for each game beyond 3 in the 7 days ending on the game day (max 15).\n- Eastward travel is weighted more because research on Major League Baseball (Song, Severini & Allada, PNAS 2017) found jet-lag effects mainly after eastward travel. The exact weights are editorial choices to make schedules comparable, not fitted to data.\n- Bands: below 25 low, 25–49 moderate, 50–74 high, 75 and above very high.\n\nA transparent heuristic for comparing schedules. It does not measure an athlete's actual fatigue, sleep or readiness.", "tags": [ "calculators" ], "x-mcp-tool": "sports_travel_fatigue_estimator", "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SportsTravelFatigueEstimatorInput" }, "examples": { "example1": { "summary": "East-coast basketball team on a western road trip", "value": { "homeBase": "Boston", "games": [ { "date": "2026-11-02", "time": "19:30", "location": "Boston", "label": "Home" }, { "date": "2026-11-04", "time": "19:00", "location": "Denver" }, { "date": "2026-11-05", "time": "19:00", "location": "Phoenix" }, { "date": "2026-11-07", "time": "19:30", "location": "Los Angeles" }, { "date": "2026-11-09", "time": "19:00", "location": "Portland" }, { "date": "2026-11-10", "time": "19:00", "location": "Seattle" }, { "date": "2026-11-12", "time": "19:30", "location": "Boston", "label": "Home" } ] } }, "example2": { "summary": "European club: league and Champions League week", "value": { "homeBase": "Munich", "games": [ { "date": "2026-09-19", "time": "15:30", "location": "Munich" }, { "date": "2026-09-23", "time": "21:00", "location": "Lisbon" }, { "date": "2026-09-26", "time": "18:30", "location": "Hamburg" }, { "date": "2026-09-30", "time": "21:00", "location": "Istanbul" }, { "date": "2026-10-03", "time": "15:30", "location": "Munich" } ] } } } } } }, "responses": { "200": { "description": "Calculation result envelope.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SportsTravelFatigueEstimatorResult" } } } }, "400": { "description": "Malformed JSON body.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "422": { "description": "Invalid input (see errors[]).", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "429": { "description": "Rate limit exceeded (see Retry-After).", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } } } } }, "/api/v1/tool": { "get": { "operationId": "getToolDefinition", "summary": "Inputs, output schema and examples for this tool", "responses": { "200": { "description": "Tool definition.", "content": { "application/json": { "schema": { "type": "object" } } } } } } } }, "components": { "schemas": { "Problem": { "type": "object", "description": "RFC 9457 problem details. 422 responses include per-field `errors`.", "required": [ "type", "title", "status", "detail" ], "properties": { "type": { "type": "string" }, "title": { "type": "string" }, "status": { "type": "integer" }, "detail": { "type": "string" }, "code": { "type": "string" }, "errors": { "type": "array", "items": { "type": "object", "required": [ "field", "message" ], "properties": { "field": { "type": "string" }, "message": { "type": "string" } } } } } }, "SportsTravelFatigueEstimatorInput": { "type": "object", "additionalProperties": false, "properties": { "homeBase": { "title": "Starting city", "description": "A city from the bundled list (118 major sports cities) or coordinates like 42.36,-71.06.", "type": "string", "maxLength": 80, "default": "Boston" }, "homeTimeZone": { "title": "Starting time zone", "description": "Only needed for coordinates: an IANA zone like America/New_York or an offset like -5.", "type": "string", "maxLength": 40 }, "games": { "title": "Games", "description": "In date order. Location: a listed city or latitude,longitude. Time zone is only needed for coordinates.", "type": "array", "minItems": 1, "maxItems": 100, "items": { "type": "object", "additionalProperties": false, "properties": { "date": { "title": "Date", "type": "string", "format": "date" }, "time": { "title": "Start time (local)", "type": "string", "pattern": "^([01]\\d|2[0-3]):[0-5]\\d$" }, "location": { "title": "City or lat,lon", "type": "string", "maxLength": 80 }, "timeZone": { "title": "Time zone", "type": "string", "maxLength": 40 }, "label": { "title": "Opponent / note", "type": "string", "maxLength": 60 } }, "required": [ "date", "location" ] } } }, "required": [ "homeBase", "games" ] }, "SportsTravelFatigueEstimatorResult": { "type": "object", "additionalProperties": false, "required": [ "schemaVersion", "tool", "computedAt", "inputs", "summary", "result", "units", "assumptions", "sources", "warnings", "presentation", "links" ], "properties": { "schemaVersion": { "type": "string", "const": "1.0" }, "tool": { "type": "object", "additionalProperties": false, "required": [ "id", "name", "version" ], "properties": { "id": { "type": "string" }, "name": { "type": "string" }, "version": { "type": "string" } } }, "computedAt": { "type": "string", "format": "date-time" }, "inputs": { "type": "object", "description": "Normalised inputs actually used, including applied defaults." }, "summary": { "type": "string" }, "result": { "type": "object", "additionalProperties": false, "required": [ "games", "totals", "weights", "cityListVersion" ], "properties": { "games": { "type": "array", "items": { "type": "object", "additionalProperties": false, "required": [ "n", "date", "location", "label", "from", "km", "timeZone", "utcOffsetHours", "shiftHours", "direction", "daysSincePrevious", "restDays", "backToBack", "gamesLast7Days", "components", "score", "band" ], "properties": { "n": { "type": "integer" }, "date": { "type": "string" }, "location": { "type": "string" }, "label": { "type": [ "string", "null" ] }, "from": { "type": "string" }, "km": { "type": "number" }, "timeZone": { "type": "string" }, "utcOffsetHours": { "type": "number" }, "shiftHours": { "type": "number", "description": "Positive = clocks ahead (eastward), negative = westward." }, "direction": { "type": "string", "enum": [ "east", "west", "none" ] }, "daysSincePrevious": { "type": [ "integer", "null" ] }, "restDays": { "type": [ "integer", "null" ] }, "backToBack": { "type": "boolean" }, "gamesLast7Days": { "type": "integer" }, "components": { "type": "object", "additionalProperties": false, "required": [ "travel", "timezone", "residualHours", "rest", "density" ], "properties": { "travel": { "type": "number" }, "timezone": { "type": "number" }, "residualHours": { "type": "number" }, "rest": { "type": "number" }, "density": { "type": "number" } } }, "score": { "type": "number" }, "band": { "type": "string", "enum": [ "low", "moderate", "high", "very high" ] } } } }, "totals": { "type": "object", "additionalProperties": false, "required": [ "km", "timeZoneHoursCrossed", "backToBacks", "averageScore", "maxScore", "hardestGame" ], "properties": { "km": { "type": "number" }, "timeZoneHoursCrossed": { "type": "number" }, "backToBacks": { "type": "integer" }, "averageScore": { "type": "number" }, "maxScore": { "type": "number" }, "hardestGame": { "type": "integer" } } }, "weights": { "type": "object" }, "cityListVersion": { "type": "string" } } }, "units": { "type": "object", "additionalProperties": { "type": "string" } }, "assumptions": { "type": "array", "items": { "type": "string" } }, "sources": { "type": "array", "items": { "type": "object", "additionalProperties": false, "required": [ "title" ], "properties": { "title": { "type": "string" }, "url": { "type": "string" }, "publisher": { "type": "string" }, "retrievedAt": { "type": "string" }, "note": { "type": "string" } } } }, "warnings": { "type": "array", "items": { "type": "string" } }, "presentation": { "type": "array", "items": { "type": "object" }, "description": "Display blocks used by the human page (same data)." }, "links": { "type": "object", "additionalProperties": false, "required": [ "human", "api", "openapi", "methodology" ], "properties": { "human": { "type": "string", "format": "uri" }, "api": { "type": "string", "format": "uri" }, "openapi": { "type": "string", "format": "uri" }, "methodology": { "type": "string", "format": "uri" } } } } } } } }