Use SofaScore Live Scores, Standings & Team Search Data with Python

Get SofaScore live scores, scheduled fixtures, league standings and team/player/tournament search results across 17 sports including football, basketball and tennis.

1. Choose the data you need

Review the published README for supported collection modes, examples, and limits. The recipe below uses the current published input definition.

2. Prepare a source-based input

This JSON contains published prefills and required-field defaults. Review every value for your task before running it; it is not a promise of successful collection.

{
  "daysAhead": 0,
  "includeAdvanced": false,
  "includeComments": false,
  "includeEvents": false,
  "includeH2h": false,
  "includeIncidents": false,
  "includeLineups": false,
  "includeOdds": false,
  "includePlayerStats": false,
  "includeSquad": false,
  "includeStandings": false,
  "includeStatistics": false,
  "includeVotes": false,
  "maxItems": 3,
  "mode": "search",
  "rankingType": "fifa",
  "searchQueries": [
    "Real Madrid"
  ],
  "searchType": "all",
  "sports": [
    "football"
  ],
  "tableType": "total"
}

Download input.example.json and save your reviewed copy as input.json.

Field	Type	Required	Description
`mode`	string	required	What to fetch from SofaScore.
`searchQueries`	array	optional	Team, player, tournament or match names to resolve (mode=search).
`searchType`	string	optional	Restrict search results to one entity type (mode=search).
`sports`	array	optional	Sports for live and scheduled modes. Supported: football, basketball, tennis, american-football, aussie-rules, ice-hockey, handball, rugby, futsal, minifootball, floorball, volleyball, badminton, table-tennis, padel, snooker, baseball, cricket, esports, darts, mma, cycling, motorsport, waterpolo, bandy.
`date`	string	optional	Start date for fixtures (mode=scheduled), format YYYY-MM-DD. Defaults to today UTC.
`daysAhead`	integer	optional	Number of extra days after Date to include (mode=scheduled).
`teamIds`	array	optional	SofaScore team IDs or team page URLs (mode=team).
`playerIds`	array	optional	SofaScore player IDs or player page URLs (mode=player).
`tournamentIds`	array	optional	SofaScore unique-tournament IDs or tournament page URLs (modes tournament, standings).
`eventIds`	array	optional	SofaScore match IDs or match page URLs (mode=event).
`seasonId`	integer	optional	Optional season ID for standings or tournament mode. If omitted, the latest season with a table is used.
`tableType`	string	optional	Standings table to fetch (modes standings, tournament).
`rankingType`	string	optional	Ranking table to fetch (mode=rankings).
`includeStatistics`	boolean	optional	Add team and player statistics to match records.
`includeLineups`	boolean	optional	Add lineups, formations and player ratings to match records.
`includeIncidents`	boolean	optional	Add goals, cards and substitutions to match records.
`includeOdds`	boolean	optional	Add pre-match odds markets to match records.
`includeVotes`	boolean	optional	Add crowd prediction polls to match records.
`includeH2h`	boolean	optional	Add head-to-head win/draw tallies to match records.
`includeAdvanced`	boolean	optional	Add shotmap, momentum, average positions, best players, win probability, managers, streaks and pre-game form.
`includeComments`	boolean	optional	Add the text commentary feed to match records. This is a large payload.
`includeSquad`	boolean	optional	Add the full squad to team records (mode=team).
`includePlayerStats`	boolean	optional	Add per-competition season statistics to player records (mode=player).
`includeStandings`	boolean	optional	Add the league table to tournament records (mode=tournament).
`includeEvents`	boolean	optional	Add recent and upcoming events to team records (mode=team).
`maxItems`	integer	optional	Maximum number of records to return. 0 means no user limit (hard cap 10,000).

3. Start an Actor run

Set APIFY_TOKEN in your environment. Python 3.10 or newer is sufficient; this recipe uses no third-party packages.

Execution may incur charges. Review current pricing on Apify. The request asks for a 120-second timeout and a charge limit; these settings are subject to Apify’s pricing and do not guarantee an all-inclusive spending cap.

import json
import os
import urllib.request

# Save the schema-derived example as input.json; review and edit it first.
with open("input.json", encoding="utf-8") as stream:
    actor_input = json.load(stream)

token = os.environ["APIFY_TOKEN"]
request = urllib.request.Request(
    "https://api.apify.com/v2/acts/6CGFPyX8guKwUQVkG/runs?timeout=120&maxTotalChargeUsd=0.50",
    data=json.dumps(actor_input).encode("utf-8"),
    headers={"Authorization": "Bearer " + token, "Content-Type": "application/json"},
    method="POST",
)
# This starts a potentially billable run. Do not automatically retry this POST.
with urllib.request.urlopen(request, timeout=40) as response:
    run = json.load(response)["data"]
print("Run ID:", run["id"])
print("Status:", run["status"])
# Inspect and download results in Apify Console once the run succeeds.

4. Inspect the actual results

Open the run in Apify Console and wait for a successful completion. Use the published output schema to locate results and the dataset schema to understand declared views. Missing or optional record fields must not be treated as guaranteed values.

Live scores, fixtures, standings, team and player profiles, match details and ranking rows from SofaScore.

Questions before you run

Which inputs are required?

The published required fields are mode

What does this guide verify?

The fields, prefills, and schema links are rendered from the published build. This is a usage recipe, not a paid live extraction test. Source availability and collection results can vary.

What if the run request times out?

Check Apify Console before retrying. The first request may already have created a run. Do not automatically repeat a run-creation POST.

Open on Apify Full Actor reference

Generated from source build q6GdIjB6lSnB3zonj and its README and schemas. Source changes regenerate this guide; no third-party editorial claims are inferred.