{"openapi":"3.0.0","info":{"title":"Global-Football-API","version":"2.0.0","description":"Live scores, fixtures, results, standings, clubs, squads and full play-by-play match timelines across 16 top-flight competitions worldwide. Every response is served from a normalized database rather than proxied live, so response shapes stay stable and latency does not depend on a third-party provider. Values are stored snapshots - call GET /get/soccer/meta to inspect current coverage and synchronization time. Missing data is returned as an empty array or null and is never fabricated.","contact":{"name":"Free Football Live Scores","url":"https://github.com/rezarahiminia/livescoreFootball/issues"}},"externalDocs":{"description":"Football data freshness, limitations and citation guide for AI assistants","url":"https://api.matchgrind.space/ai-data-guide.md"},"servers":[{"url":"https://api.matchgrind.space","description":"Configured server"}],"tags":[{"name":"Soccer Data","description":"Multi-league club data read from MongoDB"},{"name":"Health","description":"Service and database health"}],"components":{"schemas":{"Error":{"type":"object","properties":{"error":{"type":"string"}}},"League":{"type":"object","properties":{"id":{"type":"string"},"name":{"type":"string"},"abbreviation":{"type":"string"},"slug":{"type":"string","example":"eng.1"},"country":{"type":"string","example":"England"},"kind":{"type":"string","enum":["club","international"]},"logo":{"type":"string"},"active":{"type":"boolean"},"lastSyncedAt":{"type":"string","format":"date-time","nullable":true},"coverage":{"$ref":"#/components/schemas/Coverage"}}},"Coverage":{"type":"object","required":["matches","clubs","dedicatedClubs","standingsGroups","hasData"],"properties":{"matches":{"type":"integer","minimum":0},"clubs":{"type":"integer","minimum":0,"description":"Best available club count, including match-derived participants"},"dedicatedClubs":{"type":"integer","minimum":0,"description":"Full documents stored in soccer_clubs"},"standingsGroups":{"type":"integer","minimum":0},"hasData":{"type":"boolean"}}},"Club":{"type":"object","properties":{"id":{"type":"string"},"name":{"type":"string"},"displayName":{"type":"string"},"shortDisplayName":{"type":"string"},"abbreviation":{"type":"string"},"country":{"type":"string"},"city":{"type":"string"},"logo":{"type":"string"},"color":{"type":"string"},"foundedYear":{"type":"integer","nullable":true},"venue":{"type":"object","nullable":true},"isActive":{"type":"boolean"},"catalogSource":{"type":"string","enum":["club-catalog","match-snapshot"]}}},"ServiceMeta":{"type":"object","properties":{"service":{"type":"object"},"coverage":{"type":"object","properties":{"competitions":{"type":"integer"},"activeClubCompetitions":{"type":"integer"},"activeInternationalCompetitions":{"type":"integer"},"competitionsWithMatches":{"type":"integer"},"dedicatedClubDocuments":{"type":"integer"},"matches":{"type":"integer"},"playByPlayEvents":{"type":"integer"},"standingsGroups":{"type":"integer"}}},"features":{"type":"array","items":{"type":"string"}},"lastSuccessfulSyncAt":{"type":"string","format":"date-time","nullable":true},"generatedAt":{"type":"string","format":"date-time"}}},"MatchStatus":{"type":"object","properties":{"clock":{"type":"number"},"displayClock":{"type":"string"},"period":{"type":"integer"},"type":{"type":"object","properties":{"name":{"type":"string"},"state":{"type":"string","enum":["pre","in","post","unknown"]},"completed":{"type":"boolean"},"description":{"type":"string"},"detail":{"type":"string"},"shortDetail":{"type":"string"}}}}},"MatchDataAvailability":{"type":"object","description":"Storage-backed match features and intentionally unavailable league-wide data","properties":{"timeline":{"type":"object","properties":{"available":{"type":"boolean","example":true},"storedIn":{"type":"string","example":"soccer_match_events"}}},"matchGoals":{"type":"object","properties":{"available":{"type":"boolean","example":true},"storedIn":{"type":"array","items":{"type":"string"},"example":["soccer_match_events","soccer_matches.key_events"]}}},"statisticsAndSummary":{"type":"object","properties":{"available":{"type":"boolean","example":true},"storedIn":{"type":"string","example":"soccer_matches"}}},"leagueTopScorers":{"type":"object","properties":{"available":{"type":"boolean","example":false},"reason":{"type":"string"}}}}},"MatchSummary":{"type":"object","description":"Stored match summary with score, teams, statistics, key events, and data availability","properties":{"header":{"type":"object"},"boxscore":{"type":"object"},"keyEvents":{"type":"array","description":"Goals, cards, and other important events; goal items have scoringPlay=true and may include athletesInvolved","items":{"type":"object"}},"rosters":{"type":"array","items":{"type":"object"}},"gameInfo":{"type":"object"},"commentary":{"type":"array","items":{"type":"object"}},"meta":{"type":"object","properties":{"dataSource":{"type":"string","example":"database"},"provider":{"type":"string","example":"upstream"},"lastSyncedAt":{"type":"string","format":"date-time","nullable":true},"dataAvailability":{"$ref":"#/components/schemas/MatchDataAvailability"}}}}},"MatchPlay":{"type":"object","properties":{"id":{"type":"string"},"type":{"type":"object","properties":{"id":{"type":"string"},"text":{"type":"string","example":"Goal"},"type":{"type":"string","example":"goal"}}},"text":{"type":"string"},"period":{"type":"object"},"clock":{"type":"object"},"scoringPlay":{"type":"boolean"},"scoreValue":{"type":"number"},"redCard":{"type":"boolean"},"yellowCard":{"type":"boolean"},"penaltyKick":{"type":"boolean"},"ownGoal":{"type":"boolean"},"substitution":{"type":"boolean"},"team":{"type":"object","nullable":true},"athletesInvolved":{"type":"array","items":{"type":"object"}},"participants":{"type":"array","description":"Players involved in an event; substitution events normally contain the incoming and outgoing players","items":{"type":"object"}}}}}},"paths":{"/get/soccer/leagues":{"get":{"summary":"List available soccer leagues","tags":["Soccer Data"],"security":[],"parameters":[{"in":"query","name":"kind","schema":{"type":"string","enum":["club","international","all"],"default":"club"},"description":"Competition type; the club catalog is the default"},{"in":"query","name":"available","schema":{"type":"boolean","default":false},"description":"When true, only competitions with stored matches, clubs, or standings are returned"}],"responses":{"200":{"description":"Active leagues that customers can select"}}}},"/get/soccer/meta":{"get":{"summary":"Get service capabilities and current database coverage","tags":["Soccer Data"],"security":[],"responses":{"200":{"description":"Live collection counts, competition coverage, freshness, and supported features","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ServiceMeta"}}}}}}},"/get/soccer/{league}/scoreboard":{"get":{"summary":"Get stored scores and fixtures for a league and date","tags":["Soccer Data"],"security":[],"parameters":[{"in":"path","name":"league","required":true,"schema":{"type":"string"}},{"in":"query","name":"dates","schema":{"type":"string","pattern":"^\\\\d{8}$"},"description":"Date in YYYYMMDD format; defaults to current UTC date"}],"responses":{"200":{"description":"Provider-compatible scoreboard read only from MongoDB"},"404":{"description":"League not found"}}}},"/get/soccer/{league}/fixtures":{"get":{"summary":"List stored fixtures and results for a league","description":"Returns a paginated schedule. Unlike scoreboard, a date is optional and the full stored league schedule can be browsed.","tags":["Soccer Data"],"security":[],"parameters":[{"in":"path","name":"league","required":true,"schema":{"type":"string"}},{"in":"query","name":"from","schema":{"type":"string","pattern":"^\\\\d{8}$"},"description":"Optional start date in YYYYMMDD"},{"in":"query","name":"to","schema":{"type":"string","pattern":"^\\\\d{8}$"},"description":"Optional end date in YYYYMMDD"},{"in":"query","name":"status","schema":{"type":"string","enum":["all","scheduled","live","finished"],"default":"all"}},{"in":"query","name":"page","schema":{"type":"integer","minimum":1,"default":1}},{"in":"query","name":"limit","schema":{"type":"integer","minimum":1,"maximum":200,"default":100}}],"responses":{"200":{"description":"Paginated provider-compatible fixtures and results"},"400":{"description":"Invalid date, status, or pagination"},"404":{"description":"League not found"}}}},"/get/soccer/{league}/summary":{"get":{"summary":"Get a stored match summary","tags":["Soccer Data"],"security":[],"parameters":[{"in":"path","name":"league","required":true,"schema":{"type":"string"}},{"in":"query","name":"event","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"Provider-compatible match summary read only from MongoDB","content":{"application/json":{"schema":{"$ref":"#/components/schemas/MatchSummary"}}}}}}},"/get/soccer/{league}/events/{eventId}":{"get":{"summary":"Get a stored match summary by event path","tags":["Soccer Data"],"security":[],"parameters":[{"in":"path","name":"league","required":true,"schema":{"type":"string"}},{"in":"path","name":"eventId","required":true,"schema":{"type":"string"}},{"in":"query","name":"fields","schema":{"type":"string"},"description":"Comma-separated sections to return, e.g. `header,keyEvents`. Omit for the full summary. Valid sections are header, boxscore, keyEvents, rosters, gameInfo, commentary, broadcasts, odds, leaders, news, videos, format, meta."}],"responses":{"200":{"description":"Provider-compatible match summary read only from MongoDB","content":{"application/json":{"schema":{"$ref":"#/components/schemas/MatchSummary"}}}},"404":{"description":"League or match not found"}}}},"/get/soccer/{league}/events/{eventId}/plays":{"get":{"summary":"Get paginated stored play-by-play events","tags":["Soccer Data"],"security":[],"parameters":[{"in":"path","name":"league","required":true,"schema":{"type":"string"}},{"in":"path","name":"eventId","required":true,"schema":{"type":"string"}},{"in":"query","name":"page","schema":{"type":"integer","minimum":1,"default":1}},{"in":"query","name":"limit","schema":{"type":"integer","minimum":1,"maximum":300,"default":100}},{"in":"query","name":"important","schema":{"type":"boolean","default":false},"description":"When true, return only goals, cards, substitutions, and other flagged key events"}],"responses":{"200":{"description":"Paginated timeline, including goals, cards, substitutions, and other stored match events","content":{"application/json":{"schema":{"type":"object","properties":{"count":{"type":"integer"},"pageIndex":{"type":"integer"},"pageSize":{"type":"integer"},"pageCount":{"type":"integer"},"dataSource":{"type":"string","example":"database"},"items":{"type":"array","items":{"$ref":"#/components/schemas/MatchPlay"}}}}}}}}}},"/get/soccer/{league}/clubs":{"get":{"summary":"List stored clubs in a league","tags":["Soccer Data"],"security":[],"parameters":[{"in":"path","name":"league","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"Clubs in the selected league"}}}},"/get/soccer/{league}/clubs/{clubId}":{"get":{"summary":"Get a stored club, roster, and coach","tags":["Soccer Data"],"security":[],"parameters":[{"in":"path","name":"league","required":true,"schema":{"type":"string"}},{"in":"path","name":"clubId","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"Club details"},"404":{"description":"League or club not found"}}}},"/get/soccer/{league}/standings":{"get":{"summary":"Get stored standings for a league","tags":["Soccer Data"],"security":[],"parameters":[{"in":"path","name":"league","required":true,"schema":{"type":"string"}},{"in":"query","name":"season","schema":{"type":"integer"}}],"responses":{"200":{"description":"League or group standings"}}}},"/health":{"get":{"summary":"Health check endpoint","description":"Check the health status of the API and database connection","tags":["Health"],"security":[],"responses":{"200":{"description":"Service is healthy","content":{"application/json":{"schema":{"type":"object","properties":{"status":{"type":"string","example":"healthy"},"timestamp":{"type":"string","format":"date-time"},"uptime":{"type":"number","description":"Server uptime in seconds"},"version":{"type":"string","example":"2.0.0"},"database":{"type":"object","properties":{"status":{"type":"string","example":"connected"},"name":{"type":"string"}}}}}}}},"503":{"description":"Service is unhealthy"}}}},"/api/health":{"get":{"summary":"API health check (alias)","description":"Alternative endpoint for health check","tags":["Health"],"security":[],"responses":{"200":{"description":"Service is healthy"}}}}}}