{ "openapi": "3.1.1", "info": { "title": "Sports What-If Simulator API", "version": "1.0.0", "summary": "Simulate a match or a small league with a Poisson goal model — and replay “what if”.", "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://sportswhatifsimulator.usefulweb.site" } ], "paths": { "/api/v1/calculate": { "post": { "operationId": "calculate", "summary": "Simulate a match or a small league with a Poisson goal model — and replay “what if”.", "description": "Give team strengths as goals scored/conceded per game or as Elo ratings. Get exact win/draw/loss odds and a scoreline heatmap for one match, or simulate the rest of a small league thousands of times (seeded, reproducible) for title and position odds — then change any result to see how the table and the odds would have looked.\n\nMethodology:\n- Goals are modelled as independent Poisson variables. Goals model (Maher): with μ = the average goals scored per team per game, home expected goals = μ × (home scoring ÷ μ) × (away conceding ÷ μ), and the same for the away side.\n- Elo model: with d = Elo difference, home expected goals = G/2 × 10^(d/1000) and away = G/2 × 10^(−d/1000), where G is the average goals per match. With G = 2.6 this reproduces the Elo expected score (win + ½ draw) within about 2 percentage points for differences up to 400 (200 points: 76% expected score = 66% wins + 20% draws); it is a calibration, not a model fitted to real results.\n- Home advantage multiplies the home side’s expected goals (default +10%); expected goals are clamped to 0.05–8.\n- Single match: win/draw/loss and scoreline probabilities are exact sums over the Poisson grid (0–15 goals each). A seeded simulation of the same match is shown next to them as a check.\n- League: every unplayed fixture is simulated N times with a seeded sfc32 generator; the table uses 3 points per win, 1 per draw, then goal difference, goals scored and a random draw. The what-if scenario re-runs with the same random numbers (common random numbers), so differences come from the changed results, not from noise.\n\nFor fun and for “what if” arguments, not for betting: the model ignores injuries, form, motivation and the correlation between the two teams’ goals.", "tags": [ "fun" ], "x-mcp-tool": "sports_what_if_simulator", "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SportsWhatIfSimulatorInput" }, "examples": { "example1": { "summary": "One match from goal averages", "value": { "mode": "match", "model": "goals", "teams": [ { "name": "Rovers", "goalsFor": 1.9, "goalsAgainst": 0.9 }, { "name": "United", "goalsFor": 1.3, "goalsAgainst": 1.2 }, { "name": "City", "goalsFor": 1.1, "goalsAgainst": 1.4 }, { "name": "Athletic", "goalsFor": 0.9, "goalsAgainst": 1.7 } ], "homeTeam": "United", "awayTeam": "Rovers", "homeAdvantage": 10, "simulations": 2000 } }, "example2": { "summary": "Four-team league run-in with a what-if", "value": { "mode": "league", "model": "elo", "teams": [ { "name": "Rovers", "elo": 1620 }, { "name": "United", "elo": 1580 }, { "name": "City", "elo": 1500 }, { "name": "Athletic", "elo": 1450 } ], "avgGoals": 2.6, "homeAdvantage": 10, "fixtures": [ { "home": "Rovers", "away": "United", "homeGoals": 1, "awayGoals": 1 }, { "home": "City", "away": "Athletic", "homeGoals": 2, "awayGoals": 0 }, { "home": "United", "away": "City", "homeGoals": 3, "awayGoals": 1 }, { "home": "Athletic", "away": "Rovers", "homeGoals": 0, "awayGoals": 2 }, { "home": "Rovers", "away": "City" }, { "home": "United", "away": "Athletic" }, { "home": "United", "away": "Rovers" }, { "home": "Athletic", "away": "City" }, { "home": "City", "away": "United" }, { "home": "Rovers", "away": "Athletic" }, { "home": "City", "away": "Rovers" }, { "home": "Athletic", "away": "United" } ], "whatIf": [ { "home": "Rovers", "away": "United", "homeGoals": 2, "awayGoals": 1 } ], "simulations": 2000, "seed": "season-2026" } } } } } }, "responses": { "200": { "description": "Calculation result envelope.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SportsWhatIfSimulatorResult" } } } }, "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" } } } } } }, "SportsWhatIfSimulatorInput": { "type": "object", "additionalProperties": false, "properties": { "mode": { "title": "Simulate", "type": "string", "enum": [ "match", "league" ], "default": "match" }, "model": { "title": "Team strength from", "type": "string", "enum": [ "goals", "elo" ], "default": "goals" }, "teams": { "title": "Teams", "type": "array", "minItems": 2, "maxItems": 16, "items": { "type": "object", "additionalProperties": false, "properties": { "name": { "title": "Team", "type": "string", "maxLength": 40 }, "goalsFor": { "title": "Goals scored per game", "type": "number", "minimum": 0, "maximum": 10 }, "goalsAgainst": { "title": "Goals conceded per game", "type": "number", "minimum": 0, "maximum": 10 }, "elo": { "title": "Elo rating", "type": "number", "minimum": 0, "maximum": 4000 } }, "required": [ "name" ] } }, "homeTeam": { "title": "Home team (one match)", "description": "Empty = first team in the list.", "type": "string", "maxLength": 40 }, "awayTeam": { "title": "Away team (one match)", "description": "Empty = second team in the list.", "type": "string", "maxLength": 40 }, "neutral": { "title": "Neutral venue (no home advantage) for the single match", "type": "boolean", "default": false }, "homeAdvantage": { "title": "Home advantage", "type": "number", "minimum": 0, "maximum": 100, "default": 10, "x-unit": "% more expected goals" }, "avgGoals": { "title": "Average goals per match (Elo model)", "type": "number", "minimum": 0.2, "maximum": 12, "default": 2.6 }, "fixtures": { "title": "League fixtures and results", "description": "Leave the goals empty for games not played yet. No fixtures = a double round robin with nothing played.", "type": "array", "maxItems": 240, "items": { "type": "object", "additionalProperties": false, "properties": { "home": { "title": "Home", "type": "string", "maxLength": 40 }, "away": { "title": "Away", "type": "string", "maxLength": 40 }, "homeGoals": { "title": "Home goals", "type": "integer", "minimum": 0, "maximum": 99 }, "awayGoals": { "title": "Away goals", "type": "integer", "minimum": 0, "maximum": 99 } }, "required": [ "home", "away" ] } }, "whatIf": { "title": "What if… (changed results)", "description": "Override the result of a fixture (played or not) to compare the table and the odds.", "type": "array", "maxItems": 20, "items": { "type": "object", "additionalProperties": false, "properties": { "home": { "title": "Home", "type": "string", "maxLength": 40 }, "away": { "title": "Away", "type": "string", "maxLength": 40 }, "homeGoals": { "title": "Home goals", "type": "integer", "minimum": 0, "maximum": 99 }, "awayGoals": { "title": "Away goals", "type": "integer", "minimum": 0, "maximum": 99 } }, "required": [ "home", "away", "homeGoals", "awayGoals" ] } }, "simulations": { "title": "Simulations", "type": "integer", "minimum": 100, "maximum": 50000, "default": 5000 }, "seed": { "title": "Seed (optional)", "description": "Same seed = same simulated numbers. Empty = derived from the inputs.", "type": "string", "maxLength": 60 } }, "required": [ "teams" ] }, "SportsWhatIfSimulatorResult": { "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": [ "mode", "model", "seed", "seedDerived", "simulations", "match", "league" ], "properties": { "mode": { "type": "string", "enum": [ "match", "league" ] }, "model": { "type": "string", "enum": [ "goals", "elo" ] }, "seed": { "type": "string" }, "seedDerived": { "type": "boolean" }, "simulations": { "type": "integer" }, "match": { "type": [ "object", "null" ], "additionalProperties": false, "required": [ "home", "away", "expectedGoals", "probabilities", "simulated", "topScores", "neutral" ], "properties": { "home": { "type": "string" }, "away": { "type": "string" }, "neutral": { "type": "boolean" }, "expectedGoals": { "type": "object", "additionalProperties": false, "required": [ "home", "away" ], "properties": { "home": { "type": "number" }, "away": { "type": "number" } } }, "probabilities": { "type": "object", "additionalProperties": false, "required": [ "home", "draw", "away" ], "properties": { "home": { "type": "number" }, "draw": { "type": "number" }, "away": { "type": "number" } } }, "simulated": { "type": "object", "additionalProperties": false, "required": [ "home", "draw", "away" ], "properties": { "home": { "type": "number" }, "draw": { "type": "number" }, "away": { "type": "number" } } }, "topScores": { "type": "array", "items": { "type": "object", "additionalProperties": false, "required": [ "score", "probability" ], "properties": { "score": { "type": "string" }, "probability": { "type": "number" } } } } } }, "league": { "type": [ "object", "null" ], "additionalProperties": false, "required": [ "played", "remaining", "table", "odds", "whatIf" ], "properties": { "played": { "type": "integer" }, "remaining": { "type": "integer" }, "table": { "type": "array", "items": { "type": "object" } }, "odds": { "type": "array", "items": { "type": "object", "additionalProperties": false, "required": [ "team", "title", "top2", "bottom", "expectedPoints", "averagePosition" ], "properties": { "team": { "type": "string" }, "title": { "type": "number" }, "top2": { "type": "number" }, "bottom": { "type": "number" }, "expectedPoints": { "type": "number" }, "averagePosition": { "type": "number" } } } }, "whatIf": { "type": [ "object", "null" ], "additionalProperties": false, "required": [ "changes", "table", "odds" ], "properties": { "changes": { "type": "array", "items": { "type": "string" } }, "table": { "type": "array", "items": { "type": "object" } }, "odds": { "type": "array", "items": { "type": "object", "additionalProperties": false, "required": [ "team", "title", "top2", "bottom", "expectedPoints", "averagePosition" ], "properties": { "team": { "type": "string" }, "title": { "type": "number" }, "top2": { "type": "number" }, "bottom": { "type": "number" }, "expectedPoints": { "type": "number" }, "averagePosition": { "type": "number" } } } } } } } } } }, "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" } } } } } } } }