SofaScore has no public API; it offers free widgets for websites and partnerships for businesses. The JSON its own site loads is undocumented and returns 403 to plain requests. To get scores, xG, shots and possession into code, you use an API that reads SofaScore's public match data. Ours does, and the script below saves a matchday's stats to CSV.
What SofaScore offers developers
SofaScore offers embeddable widgets, not a data API. A widget is an iframe you paste into your CMS to show live scores, free and without limits. If you only want a live score on your site, a widget is the better pick. The corporate site lists advertising, media and sports partnerships, with no developer documentation. The JSON at api.sofascore.com has no docs either, and the sofascore-wrapper package on PyPI moved to a Chromium-based client once plain requests started getting 403.
SofaScore match stats with ToolzerHub
We make ToolzerHub. Our SofaScore API has 287 routes covering football, tennis, basketball, cricket, MMA, motorsport and esports, each a GET with the x-api-key header at 1 credit a call. Three of them cover a matchday:
/v1/sofascore/events/day?sport=football&date=...returns every event in a sport on a day, one page at a time./v1/sofascore/tournament/events/day?tournament_id_or_url=...&date=...returns one tournament's matches on a day./v1/sofascore/event/statistics?event_id_or_url=...returns a match's statistics.
One page of a football day held 220 events, 204 of them finished, from the AFC Champions League Elite to Japanese university football. Events keep SofaScore's own shape: tournament, season, roundInfo, status, homeTeam, awayTeam and homeScore.
export TOOLZERHUB_API_KEY=your_key
curl -G -H "x-api-key: $TOOLZERHUB_API_KEY" \
--data-urlencode "event_id_or_url=16938783" \
"https://api.toolzerhub.com/v1/sofascore/event/statistics"
Barcelona 3-0 Aston Villa, the full-match overview, trimmed:
{
"event_id": 16938783,
"periods": [
{
"period": "ALL",
"groups": [
{
"name": "Match overview",
"items": [
{ "key": "ballPossession", "name": "Ball possession", "home": "65%", "away": "35%", "home_value": 65, "away_value": 35 },
{ "key": "expectedGoals", "name": "Expected goals", "home": "1.86", "away": "0.71", "home_value": 1.86, "away_value": 0.71 },
{ "key": "bigChanceCreated", "name": "Big chances", "home": "5", "away": "1", "home_value": 5, "away_value": 1 },
{ "key": "totalShotsOnGoal", "name": "Total shots", "home": "16", "away": "9", "home_value": 16, "away_value": 9 },
{ "key": "passes", "name": "Passes", "home": "602", "away": "320", "home_value": 602, "away_value": 320 },
{ "key": "avgRating", "name": "Average rating", "home": "8.46", "away": "6.49", "home_value": 8.46, "away_value": 6.49 }
]
}
]
}
]
}
periods holds ALL, 1ST and 2ND, each split into 7 groups from Match overview to Goalkeeping. Read home_value and away_value; home and away are display strings such as 12/26 (46%). The key totalShotsOnGoal is total shots, and shotsOnGoal is shots on target.
Save a matchday's stats to CSV
The script takes a tournament id or sofascore.com tournament link, plus a date: 7 is the Champions League, 17 the Premier League. It makes 1 call for the day and 1 per finished match. Each row holds the score and 8 stats per side, from possession and xG to yellow cards. Save it as sofascore_matchday.py and install requests (pip install requests).
import csv
import os
import sys
import time
import requests
BASE = "https://api.toolzerhub.com/v1/sofascore"
HEADERS = {"x-api-key": os.environ.get("TOOLZERHUB_API_KEY", "")}
STATS = ["ballPossession", "expectedGoals", "totalShotsOnGoal", "shotsOnGoal",
"bigChanceCreated", "cornerKicks", "passes", "yellowCards"]
def get(path, params, tries=3):
for attempt in range(tries):
r = requests.get(f"{BASE}/{path}", headers=HEADERS, params=params, timeout=60)
if r.status_code in (429, 500, 502, 503, 504) and attempt < tries - 1:
time.sleep(5 * (attempt + 1))
continue
r.raise_for_status()
return r.json()["data"]
def match_stats(event_id):
# Full-match ("ALL") values; 1ST and 2ND hold the halves.
data = get("event/statistics", {"event_id_or_url": event_id}) or {"periods": []}
full = next((p for p in data["periods"] if p["period"] == "ALL"), {"groups": []})
items = {i["key"]: i for g in full["groups"] for i in g["items"]}
row = {}
for key in STATS:
item = items.get(key, {})
row[f"home_{key}"], row[f"away_{key}"] = item.get("home_value"), item.get("away_value")
return row
def main(tournament, day, out="matchday.csv"):
events = (get("tournament/events/day", {"tournament_id_or_url": tournament, "date": day})
or {"events": []})["events"]
finished = [e for e in events if e["status"]["type"] == "finished"]
print(f"{len(events)} events, {len(finished)} finished")
fields = ["date", "tournament", "event_id", "home", "away", "home_score", "away_score"] + \
[f"{side}_{k}" for k in STATS for side in ("home", "away")]
with open(out, "w", newline="", encoding="utf-8") as f:
writer = csv.DictWriter(f, fieldnames=fields)
writer.writeheader()
for e in finished:
writer.writerow({
"date": day, "tournament": e["tournament"]["name"], "event_id": e["id"],
"home": e["homeTeam"]["name"], "away": e["awayTeam"]["name"],
"home_score": e["homeScore"].get("current"), "away_score": e["awayScore"].get("current"),
**match_stats(e["id"]),
})
print(f"{len(finished)} matches saved to {out}")
if __name__ == "__main__":
if len(sys.argv) < 3:
sys.exit("usage: python sofascore_matchday.py TOURNAMENT_ID_OR_LINK YYYY-MM-DD [file.csv]")
if not HEADERS["x-api-key"]:
sys.exit("set TOOLZERHUB_API_KEY first")
main(*sys.argv[1:])
python sofascore_matchday.py 7 2026-11-03 ucl-2026-11-03.csv
We ran it on one Champions League night and a three-day Premier League matchweek. The Champions League night saved 9 matches in 10 calls and 11.1 seconds. The Premier League's busiest day saved 8 matches in 9 calls and 34.5 seconds, and a sofascore.com tournament link worked as well as the id.
What the matchday stats showed
Across the 19 matches, the team with the higher xG won 10, drew 3 and lost 6. The team with more possession won 8 of the 16 matches that had a winner, no better than chance.
Four matches where the score and the stats pulled apart, and one where they lined up:
| Match | Score | xG | Shots | Possession |
|---|---|---|---|---|
| Galatasaray v Stuttgart | 2-0 | 0.98-2.2 | 13-13 | 52-48 |
| Coventry City v Sunderland | 3-1 | 0.69-1.82 | 12-17 | 43-57 |
| Brentford v Nottingham Forest | 2-0 | 0.46-0.86 | 7-15 | 42-58 |
| Manchester City v Brighton | 0-1 | 1.64-1.0 | 21-7 | 62-38 |
| Tottenham v Crystal Palace | 2-0 | 3.47-0.14 | 34-2 | 79-21 |
Galatasaray and Coventry won on less than half their opponent's xG, and Manchester City lost with 21 shots to 7. Tottenham sits at the other end: 79% possession and 34 shots to 2 ended in a 2-0 win. Nineteen matches is a small sample; run the script over a season and each row keeps its event_id, so you can pull lineups or incidents for the matches that look odd.
What it costs
A 10-match matchweek over three days is 13 credits: 3 day calls and 10 stats calls. A full Premier League season is roughly 500. The 100 free credits a month cover one league's weekly matchweek; $19 buys 10,000 credits that never expire, and plans for higher volume cover more leagues. Set your key, pass a tournament id and a date, and the matchday is a CSV in under a minute.
For fan reaction and highlights, see our Reddit search API post and YouTube channel videos API. For tennis rankings, see does the ATP have an API; to compare free football data, free football APIs compared.
We are not affiliated with SofaScore.