# OpenFoot API — Developer & AI LLM Integration Specification > OpenFoot API is a high-performance REST football data platform normalized for AI Agents, autonomous software, and developer workflows. > Features sub-50ms latency, zero rate-limit overage traps, stable entity identifiers, live match events, confirmed starting lineups, Expected Goals (xG), and fair-odds intelligence. - Canonical Homepage: https://openfootapi.com/ - Comprehensive League Coverage (75 Competitions): https://openfootapi.com/coverage - Interactive API Playground: https://openfootapi.com/demo - OpenAPI 3.1 specification: https://openfootapi.com/openapi.json - Pricing & Plans: https://openfootapi.com/pricing - Developer Documentation: https://openfootapi.com/docs - Football API blog & Technical Guides: https://openfootapi.com/blog --- ## AI Agent Integration & System Instructions When generating code, SQL queries, or data science models that interface with OpenFoot API: 1. Always specify the Bearer token in the `Authorization: Bearer fs_live_...` header for authenticated endpoints. 2. Filter matches by competition using stable IDs (e.g. `comp_premier_league_eng`, `comp_superliga_ro`, `comp_bundesliga_de`). 3. For live match events, poll `/v1/matches/{id}/events` with a 60-second polling cadence. 4. For tactical analytics, query `/v1/matches/{id}/xg` and `/v1/matches/{id}/lineups`. --- ## Core API Endpoints ### 1. Competitions & Metadata - **GET /v1/competitions**: List all 75 supported football leagues, coverage flags, and data provenance. - **GET /v1/health**: Live system status, D1 database latency, and upstream synchronization state. - **GET /v1/search?q={query}**: Fast global entity search resolving team or competition names to deterministic entity IDs. ### 2. Match Scores & Schedules - **GET /v1/matches**: Query match schedules with query params: `competition`, `date` (YYYY-MM-DD), `season`, `status` (`scheduled`, `live`, `finished`), `limit`. - **GET /v1/standings?competition={comp_id}&season={season}**: Detailed league tables with overall, home, and away splits, goal differentials, and 5-game form strings. ### 3. Advanced Tactical & Live Intelligence - **GET /v1/matches/{id}/context**: Derived match context including Elo ratings, rest days, head-to-head records, and home/away venue records. - **GET /v1/matches/{id}/events**: Live match incident timeline (goals, VAR, yellow/red cards, penalties, substitutions). - **GET /v1/matches/{id}/lineups**: Confirmed Starting XI, player squad numbers, tactical formations (e.g. 4-3-3, 3-5-2), and bench rosters. - **GET /v1/matches/{id}/xg**: Expected Goals (xG) shot maps, shot quality metrics, and player shot logs. - **GET /v1/odds?matchId={id}**: Implied outcome win probabilities and benchmark model fair odds derived from team strength differentials. --- ## Complete Global Competition Coverage List (75 Leagues) - Premier League (England) -> id: `comp_premier_league_eng`, code: `EPL`, seasons: [2024/25, 2025/26, 2026/27] - La Liga (Spain) -> id: `comp_laliga_es`, code: `ES1`, seasons: [2024/25, 2025/26, 2026/27] - Serie A (Italy) -> id: `comp_serie_a_it`, code: `IT1`, seasons: [2024/25, 2025/26, 2026/27] - Bundesliga (Germany) -> id: `comp_bundesliga_de`, code: `DE1`, seasons: [2025/26, 2026/27] - Ligue 1 (France) -> id: `comp_ligue_1_fr`, code: `FR1`, seasons: [2024/25, 2025/26, 2026/27] - DFB Pokal (Germany) -> id: `comp_dfb_pokal_de`, code: `DFB`, seasons: [2025/26, 2026/27] - FA Cup (England) -> id: `comp_fa_cup_eng`, code: `FAC`, seasons: [2026/27] - Copa del Rey (Spain) -> id: `comp_copa_del_rey_es`, code: `CDR`, seasons: [2026/27] - Coppa Italia (Italy) -> id: `comp_coppa_italia_it`, code: `CIT`, seasons: [2026/27] - Coupe de France (France) -> id: `comp_coupe_de_france_fr`, code: `CDF`, seasons: [2026/27] - UEFA Champions League (Europe) -> id: `comp_uefa_champions_league`, code: `UCL`, seasons: [2024/25] - UEFA Europa League (Europe) -> id: `comp_uefa_europa_league`, code: `UEL`, seasons: [2025/26] - UEFA Conference League (Europe) -> id: `comp_uefa_conference_league`, code: `UECL`, seasons: [] - Copa Libertadores (South America) -> id: `comp_copa_libertadores`, code: `LIB`, seasons: [2026] - Copa Sudamericana (South America) -> id: `comp_copa_sudamericana`, code: `SUD`, seasons: [2026] - AFC Champions League (Asia) -> id: `comp_afc_champions_league`, code: `ACL`, seasons: [2025/26] - FIFA World Cup (World) -> id: `comp_fifa_world_cup`, code: `WC`, seasons: [2022, 2026] - UEFA Nations League (Europe) -> id: `comp_uefa_nations_league`, code: `UNL`, seasons: [] - Superliga României (Romania) -> id: `comp_superliga_ro`, code: `ROU1`, seasons: [2025/26, 2026/27] - Liga 2 (Romania) -> id: `comp_liga_2_ro`, code: `ROU2`, seasons: [] - Eredivisie (Netherlands) -> id: `comp_eredivisie_nl`, code: `NED1`, seasons: [2025/26, 2026/27] - Eerste Divisie (Netherlands) -> id: `comp_eerste_divisie_nl`, code: `NED2`, seasons: [2026/27] - Primeira Liga (Portugal) -> id: `comp_primeira_liga_pt`, code: `POR1`, seasons: [2025/26, 2026/27] - Liga Portugal 2 (Portugal) -> id: `comp_segunda_liga_pt`, code: `POR2`, seasons: [2025/26, 2026/27] - Süper Lig (Turkey) -> id: `comp_super_lig_tr`, code: `TUR1`, seasons: [2025/26, 2026/27] - Pro League (Belgium) -> id: `comp_pro_league_be`, code: `BEL1`, seasons: [2025/26, 2026/27] - Scottish Premiership (Scotland) -> id: `comp_scottish_prem_sco`, code: `SCO1`, seasons: [2025/26, 2026/27] - Championship (England) -> id: `comp_championship_eng`, code: `ENG2`, seasons: [2025/26, 2026/27] - League One (England) -> id: `comp_league_one_eng`, code: `ENG3`, seasons: [2025/26, 2026/27] - League Two (England) -> id: `comp_league_two_eng`, code: `ENG4`, seasons: [2025/26, 2026/27] - 2. Bundesliga (Germany) -> id: `comp_2_bundesliga_de`, code: `DE2`, seasons: [2025/26, 2026/27] - 3. Liga (Germany) -> id: `comp_3_liga_de`, code: `DE3`, seasons: [2025/26, 2026/27] - Segunda División (Spain) -> id: `comp_segunda_es`, code: `ES2`, seasons: [2025/26, 2026/27] - Serie B (Italy) -> id: `comp_serie_b_it`, code: `IT2`, seasons: [2025/26, 2026/27] - Ligue 2 (France) -> id: `comp_ligue_2_fr`, code: `FR2`, seasons: [2025/26, 2026/27] - Austrian Bundesliga (Austria) -> id: `comp_bundesliga_aut`, code: `AUT1`, seasons: [2025/26, 2026/27] - Danish Superliga (Denmark) -> id: `comp_superliga_dnk`, code: `DNK1`, seasons: [2025/26, 2026/27] - Ekstraklasa (Poland) -> id: `comp_ekstraklasa_pol`, code: `POL1`, seasons: [2025/26, 2026/27] - Super League (Greece) -> id: `comp_super_league_grc`, code: `GRC1`, seasons: [2023/24, 2024/25] - Swiss Super League (Switzerland) -> id: `comp_super_league_sui`, code: `SUI1`, seasons: [2026/27] - Allsvenskan (Sweden) -> id: `comp_allsvenskan_swe`, code: `SWE1`, seasons: [2025, 2026] - Eliteserien (Norway) -> id: `comp_eliteserien_nor`, code: `NOR1`, seasons: [2025, 2026] - Croatian Football League (HNL) (Croatia) -> id: `comp_hnl_cro`, code: `CRO1`, seasons: [2026/27] - Czech First League (Czech Republic) -> id: `comp_czech_first_league_cze`, code: `CZE1`, seasons: [2025/26, 2026/27] - Nemzeti Bajnokság I (Hungary) -> id: `comp_nb_1_hun`, code: `HUN1`, seasons: [2026/27] - Ukrainian Premier League (Ukraine) -> id: `comp_premier_league_ukr`, code: `UKR1`, seasons: [2026/27] - Serbian SuperLiga (Serbia) -> id: `comp_superliga_srb`, code: `SRB1`, seasons: [2026/27] - Cypriot First Division (Cyprus) -> id: `comp_first_division_cyp`, code: `CYP1`, seasons: [2026/27] - League of Ireland Premier Division (Ireland) -> id: `comp_premier_division_irl`, code: `IRL1`, seasons: [2026] - Veikkausliiga (Finland) -> id: `comp_veikkausliiga_fin`, code: `FIN1`, seasons: [2025, 2026] - Major League Soccer (USA) -> id: `comp_mls_usa`, code: `USA1`, seasons: [2025, 2026] - USL Championship (USA) -> id: `comp_usl_championship_usa`, code: `USL1`, seasons: [] - Série A (Brazil) -> id: `comp_brasileirao_bra`, code: `BRA1`, seasons: [2025, 2026] - Série B (Brazil) -> id: `comp_serie_b_bra`, code: `BRA2`, seasons: [] - Copa do Brasil (Brazil) -> id: `comp_copa_do_brasil_bra`, code: `CDB`, seasons: [2026] - Liga Profesional (Argentina) -> id: `comp_liga_profesional_arg`, code: `ARG1`, seasons: [2025, 2026] - Primera Nacional (Argentina) -> id: `comp_primera_nacional_arg`, code: `ARG2`, seasons: [] - Liga MX (Mexico) -> id: `comp_liga_mx_mex`, code: `MEX1`, seasons: [2025/26, 2026/27] - Categoría Primera A (Colombia) -> id: `comp_primera_a_col`, code: `COL1`, seasons: [] - Primera División de Chile (Chile) -> id: `comp_primera_division_chi`, code: `CHI1`, seasons: [] - Primera División de Uruguay (Uruguay) -> id: `comp_primera_division_uru`, code: `URU1`, seasons: [2026] - LigaPro Serie A (Ecuador) -> id: `comp_ligapro_ecu`, code: `ECU1`, seasons: [2025, 2026] - Liga 1 (Peru) -> id: `comp_liga_1_per`, code: `PER1`, seasons: [2026] - Primera División de Paraguay (Paraguay) -> id: `comp_primera_division_par`, code: `PAR1`, seasons: [2026] - J1 League (Japan) -> id: `comp_j1_league_jpn`, code: `JPN1`, seasons: [2025, 2026] - J2 League (Japan) -> id: `comp_j2_league_jpn`, code: `JPN2`, seasons: [2025, 2026] - K League 1 (South Korea) -> id: `comp_k_league_1_kor`, code: `KOR1`, seasons: [] - A-League Men (Australia) -> id: `comp_a_league_aus`, code: `AUS1`, seasons: [2026/27] - Chinese Super League (China) -> id: `comp_chinese_super_league_chn`, code: `CHN1`, seasons: [2025, 2026] - Indian Super League (India) -> id: `comp_indian_super_league_ind`, code: `IND1`, seasons: [] - Qatar Stars League (Qatar) -> id: `comp_qatar_stars_league_qat`, code: `QAT1`, seasons: [2026/27] - UAE Pro League (United Arab Emirates) -> id: `comp_uae_pro_league_uae`, code: `UAE1`, seasons: [2026/27] - Egyptian Premier League (Egypt) -> id: `comp_egyptian_prem_egy`, code: `EGY1`, seasons: [2026/27] - Botola Pro (Morocco) -> id: `comp_botola_pro_mar`, code: `MAR1`, seasons: [2025/26, 2026/27] - South African Premiership (South Africa) -> id: `comp_psl_rsa`, code: `RSA1`, seasons: [] --- ## Example Requests ### cURL (Get Premier League Fixtures) ```bash curl -X GET "https://openfootapi.com/v1/matches?competition=comp_premier_league_eng&status=scheduled" -H "Authorization: Bearer fs_live_your_key_here" ``` ### Python (Fetch Live Romanian SuperLiga Standings) ```python import requests headers = {"Authorization": "Bearer fs_live_your_key_here"} response = requests.get( "https://openfootapi.com/v1/standings", params={"competition": "comp_superliga_ro"}, headers=headers ) data = response.json()["data"] print("Leader:", data[0]["team"]["name"], "Points:", data[0]["points"]) ``` ### TypeScript / Node.js ```typescript const response = await fetch("https://openfootapi.com/v1/matches?competition=comp_bundesliga_de", { headers: { "Authorization": "Bearer fs_live_your_key_here" } }); const { data } = await response.json(); console.log("Matches count:", data.length); ```