Skip to content

API.md

Latest commit

 

History

History
130 lines (97 loc) · 5.03 KB

API.md

File metadata and controls

130 lines (97 loc) · 5.03 KB
Raw

REST API Documentation

The Football Market Intelligence Engine exposes a high-performance REST API built with FastAPI. This API serves the Next.js frontend, providing everything from deep historical statistics to live simulation triggers and market evaluations.

All endpoints return JSON and use standard HTTP status codes.

1. Tournaments API

Provides core data relating to World Cup editions. (Prefix: /api/tournaments)

  • GET /
    • Description: Retrieves a list of all World Cup editions (historical and upcoming).
  • GET /{year}/squads
    • Description: Fetches the registered 26-man rosters for every team in a specific World Cup year.
  • GET /{year}/matches
    • Description: Retrieves all matches (fixtures and results) for a given World Cup edition.

2. Teams API

(Prefix: /api/teams)

  • GET /
    • Description: Returns a canonical list of all historical and modern international football teams, including their official FIFA codes and confederations.

3. Matchups & Mock Simulations

Allows users to construct hypothetical matchups and run on-the-fly predictions. (Prefix: /api/matchups)

  • GET /teams
    • Description: Retrieves the list of teams available for hypothetical matchups.
  • GET /teams/{team_name}/roster
    • Description: Retrieves the active roster for a selected team to construct hypothetical starting XIs.
  • POST /simulate
    • Description: Accepts two teams and their hypothetical lineups, dynamically calculates squad value/Elo, and runs the XGBoost model to return probabilities for Home Win, Draw, and Away Win.

4. Models API

Exposes the Machine Learning subsystem for inspection and retraining. (Prefix: /api/models)

  • GET /
    • Description: Lists all registered models (e.g., "XGBoost Modern", "Logistic Regression Historical").
  • GET /status
    • Description: Returns the current deployment status, hyperparameter configuration, and feature counts of the active production models.
  • POST /train
    • Description: Triggers a background retraining pipeline, forcing the models to update based on the latest database features.

5. Market Evaluation API

Integrates with Kalshi and Polymarket. (Prefix: /api/markets)

  • GET /external
    • Description: Lists all currently active betting markets scraped from external providers.
  • GET /external/{market_id}
    • Description: Retrieves the time-series odds and liquidity history for a specific market.
  • GET /metrics
    • Description: Returns aggregate metrics regarding market ingestion volume and provider health.
  • POST /{market_id}/simulate
    • Description: Triggers the Constrained Monte Carlo engine to evaluate a specific market intent (e.g., "Will England reach the Semi-Finals?") and returns the calculated probabilities and confidence intervals.

6. Full Tournament Simulations

(Prefix: /api/simulations)

  • POST /run
    • Description: Triggers a massive, unconstrained Monte Carlo simulation of the entire World Cup bracket (e.g., 10,000 iterations).
  • GET /
    • Description: Lists all previously completed full-tournament simulation runs.
  • GET /{run_id}/results
    • Description: Returns the deep projection data for a specific run, detailing each team's exact probability of reaching every stage of the tournament.

7. Statistics API

Massive data-warehousing endpoints for dashboard visualizations. (Prefix: /api/stats)

  • GET /top-scorers
    • Description: Top historical goalscorers.
  • GET /team-win-rates
    • Description: Historical win percentages by team.
  • GET /tournament-trends
    • Description: High-level trends (goals per game, attendance) across decades.
  • GET /awards
    • Description: Golden Boot, Golden Ball, and other historical award winners.
  • GET /top-managers
    • Description: Most successful managers in international football.
  • GET /shootouts
    • Description: Historical penalty shootout conversion rates.
  • GET /stadiums
    • Description: Match counts and average attendance per stadium.

Deep Aggregation Endpoints:

  • GET /international (and sub-routes /matches, /teams, /tournaments, /scorers)
  • GET /world-cup/matches, GET /world-cup/teams, GET /world-cup/tournaments, GET /world-cup/scorers

8. Historical Datasets

(Prefix: /api/historical)

  • GET /tournaments
    • Description: Legacy route for basic tournament listings.
  • GET /squads/{year}
    • Description: Legacy route for squad retrieval.

9. Value Betting Opportunities

(Prefix: /api/opportunities)

  • GET /
    • Description: The ultimate output of the engine. Returns all active markets where the ML predicted probability significantly exceeds the Bookmaker's implied probability (EV+ bets).

10. System Health

(Prefix: /api/system)

  • GET /metrics
    • Description: Returns Prometheus-compatible system metrics, database connection health, and background task statuses.