# SofaScore Scraper ⚽ Live Scores | Teams | Players | Fixtures (`abotapi/sofascore-scraper`) Actor From $1/1K. Pull structured sports data from SofaScore across football, basketball, tennis, and 20+ sports. Search by keyword, paste URLs, fetch live matches, or download fixtures by date. Returns scores, stats, lineups, incidents, odds, teams, players, tournaments, and more. - **URL**: https://apify.com/abotapi/sofascore-scraper.md - **Developed by:** [AbotAPI](https://apify.com/abotapi) (community) - **Categories:** Other, Developer tools, News - **Stats:** 5 total users, 2 monthly users, 100.0% runs succeeded, NaN bookmarks - **User rating**: No ratings yet ## Pricing from $1.00 / 1,000 results This Actor is paid per event. You are not charged for the Apify platform usage, but only a fixed price for specific events. Since this Actor supports Apify Store discounts, the price gets lower the higher subscription plan you have. Learn more: https://docs.apify.com/platform/actors/running/actors-in-store#pay-per-event ## What's an Apify Actor? Actors are a software tools running on the Apify platform, for all kinds of web data extraction and automation use cases. In Batch mode, an Actor accepts a well-defined JSON input, performs an action which can take anything from a few seconds to a few hours, and optionally produces a well-defined JSON output, datasets with results, or files in key-value store. In Standby mode, an Actor provides a web server which can be used as a website, API, or an MCP server. Actors are written with capital "A". ## How to integrate an Actor? If asked about integration, you help developers integrate Actors into their projects. You adapt to their stack and deliver integrations that are safe, well-documented, and production-ready. The best way to integrate Actors is as follows. In JavaScript/TypeScript projects, use official [JavaScript/TypeScript client](https://docs.apify.com/api/client/js.md): ```bash npm install apify-client ``` In Python projects, use official [Python client library](https://docs.apify.com/api/client/python.md): ```bash pip install apify-client ``` In shell scripts, use [Apify CLI](https://docs.apify.com/cli/docs.md): ````bash # MacOS / Linux curl -fsSL https://apify.com/install-cli.sh | bash # Windows irm https://apify.com/install-cli.ps1 | iex ```bash In AI frameworks, you might use the [Apify MCP server](https://docs.apify.com/platform/integrations/mcp.md). If your project is in a different language, use the [REST API](https://docs.apify.com/api/v2.md). For usage examples, see the [API](#api) section below. For more details, see Apify documentation as [Markdown index](https://docs.apify.com/llms.txt) and [Markdown full-text](https://docs.apify.com/llms-full.txt). # README ## SofaScore Scraper Pull structured sports data from SofaScore: live scores, match statistics, lineups, incidents, betting odds, league tables, teams, players, and tournaments. Works across football, basketball, tennis, and 20+ other sports. Search by keyword, paste links, grab every live match, or download a whole day of fixtures. Every record arrives as clean JSON with 100+ fields, ready for analysis, dashboards, or model training. ### Why this scraper - **Four ways to find data, not one.** Search by keyword, paste SofaScore links, pull all live matches, or list every fixture on a date. Most scrapers only accept URLs you have to build by hand. - **Four entity types, fully expanded.** Matches, teams, players, and tournaments each come back with deep, named fields, plus the complete upstream object so nothing is lost. - **Match detail on demand.** Toggle statistics, lineups (with player ratings and formations), incidents (goals, cards, subs), and odds per run. Pay only for the depth you use. - **League tables and squads.** Tournament records can include the full standings; team records can include the entire player squad. - **20+ sports.** Football, basketball, tennis, ice hockey, American football, baseball, cricket, rugby, MMA, and more. - **Fast and lean.** Direct JSON access, no browser. Hundreds of records per run on modest memory. - **Documented output.** A full field list and a real example record are below, so you know exactly what you get before you run it. ### Data you get > Sample shape: values are illustrative placeholders, not from a live record. #### Match record | Field | Example | | --- | --- | | `type` | `"match"` | | `id` | `10000001` | | `sport` | `"football"` | | `name` | `"Home Team - Away Team"` | | `homeTeam` / `awayTeam` | `"Home Team"` / `"Away Team"` | | `homeScore` / `awayScore` | `2` / `1` | | `homeScoreHalftime` / `awayScoreHalftime` | `1` / `0` | | `statusType` | `"finished"` | | `winnerCode` | `1` | | `startTimestamp` | `1700000000` | | `tournament` / `uniqueTournament` | `"Sample League 24/25"` / `"Sample League"` | | `season` | `"24/25"` | | `round` | `12` | | `venue` / `venueCity` | `"Sample Stadium"` / `"Sample City"` | | `latitude` / `longitude` | `40.0000` / `-3.0000` | | `referee` | `"Referee Name"` | | `attendance` | `40000` | | `hasXg` | `true` | | `country` | `"Country"` | | `url` | `"https://www.sofascore.com/football/match/home-team-away-team/AbCdEf#id:10000001"` | | `statistics` | possession, shots, passes, xG (when enabled) | | `lineups` | starters, subs, formations, ratings (when enabled) | | `incidents` | goals, cards, substitutions (when enabled) | | `odds` | pre-match markets (when enabled) | | `votes` | fan prediction poll: home / draw / away counts, both-teams-to-score, first-to-score (when enabled) | | `raw` | the complete upstream match object | #### Team, player, and tournament records | Field | Example | | --- | --- | | `type` | `"team"` / `"player"` / `"tournament"` | | `id` | `2000001` | | `name` | `"Sample Team"` | | `country` | `"Country"` | | `managerName` / `venue` / `venueCapacity` (team) | `"Manager Name"` / `"Sample Stadium"` / `80000` | | `shortName` / `nameCode` / `teamColors` (team) | `"Sample"` / `"SMP"` / `{ "primary": "#ffffff" }` | | `position` / `shirtNumber` / `preferredFoot` (player) | `"F"` / `10` / `"Left"` | | `marketValue` / `marketValueCurrency` (player) | `50000000` / `"EUR"` | | `contractUntil` (player) | `1861833600` | | `tier` / `titleHolderName` / `mostTitles` (tournament) | `1` / `"Sample Champion"` / `20` | | `standings` (tournament) | full league table when enabled | | `squad` (team) | full player list when enabled | | `raw` | the complete upstream object | ### How to use **Search for a team and its stats:** ```json { "mode": "search", "searchQueries": ["Real Madrid"], "searchType": "team", "maxItems": 5 } ```` **Every live football and tennis match right now:** ```json { "mode": "live", "sports": ["football", "tennis"], "includeStatistics": true, "includeIncidents": true } ``` **All fixtures for a date, plus the next two days:** ```json { "mode": "scheduled", "sports": ["football"], "date": "2024-06-15", "daysAhead": 2, "maxItems": 200 } ``` **Paste links (match, team, player, tournament):** ```json { "mode": "url", "urls": [ "https://www.sofascore.com/team/football/real-madrid/2829", "https://www.sofascore.com/player/lionel-messi/12994" ] } ``` Match links must include the numeric id: copy the address bar while on a match page (it ends with `#id:`), or use an `/event/` link. ### Input parameters | Parameter | Type | Default | Description | | --- | --- | --- | --- | | `mode` | string | `search` | `search`, `url`, `live`, or `scheduled`. | | `searchQueries` | array | `["Real Madrid"]` | Keywords to resolve (search mode). | | `searchType` | string | `all` | Restrict a query to `team`, `player`, `tournament`, or `match`. | | `urls` | array | sample | SofaScore links (url mode). | | `sports` | array | `["football"]` | Sports for live and scheduled modes. | | `date` | string | today | `YYYY-MM-DD` for scheduled mode. | | `daysAhead` | integer | `0` | Extra days after `date`. | | `includeStatistics` | boolean | `true` | Match and player statistics. | | `includeLineups` | boolean | `true` | Match lineups and ratings. | | `includeIncidents` | boolean | `true` | Goals, cards, substitutions. | | `includeOdds` | boolean | `false` | Pre-match odds markets. | | `includeVotes` | boolean | `false` | Fan prediction poll (community sentiment) per match. | | `includeStandings` | boolean | `true` | Tournament league tables. | | `includeSquad` | boolean | `false` | Full team squads. | | `maxItems` | integer | `20` | Stop after this many records (0 = no limit). | | `proxy` | object | Apify proxy | Connection settings. | ### Output example > Sample shape: values are illustrative placeholders, not from a live record. ```json { "type": "match", "id": 10000001, "sport": "football", "name": "Home Team - Away Team", "homeTeam": "Home Team", "awayTeam": "Away Team", "homeScore": 2, "awayScore": 1, "statusType": "finished", "winnerCode": 1, "startTimestamp": 1700000000, "tournament": "Sample League", "season": "24/25", "round": 12, "venue": "Sample Stadium", "referee": "Referee Name", "attendance": 40000, "country": "Country", "url": "https://www.sofascore.com/football/match/home-team-away-team/AbCdEf#id:10000001", "statistics": [{ "period": "ALL", "groups": [] }], "incidents": [{ "incidentType": "goal", "time": 23, "player": { "name": "Player Name" } }], "raw": {} } ``` ### Connection and plans The scraper works on the Apify free plan with the default proxy and rotates connections automatically if an exit is refused. For large runs or sustained load, residential proxy (Starter plan and above) gives more rotation headroom. Pick it under the Connection section and, optionally, set a country. # Actor input Schema ## `mode` (type: `string`): How to discover what to scrape. SEARCH looks up teams/players/tournaments/matches by keyword. URL takes SofaScore links you paste. LIVE pulls every in-play match for the chosen sports. SCHEDULED pulls all fixtures for a date. ## `searchQueries` (type: `array`): Keywords to look up: team, player, tournament, or match names. Each query resolves to the top matching entities, which are then scraped in full. ## `searchType` (type: `string`): Limit which entity types a query resolves to. 'all' returns the best mix of teams, players, tournaments and matches. ## `urls` (type: `array`): Paste SofaScore links: match, team, player, or tournament pages. Match links must include the numeric id (the part after #id: in the address bar, or an /event/ link). Team/player/tournament links use the trailing numeric id. ## `sports` (type: `array`): Which sports to pull for Live and Scheduled modes. ## `date` (type: `string`): Day to pull fixtures for, in YYYY-MM-DD. Leave blank to use today (UTC). ## `daysAhead` (type: `integer`): Also pull fixtures for this many days after the chosen date. 0 = just the one day. ## `includeStatistics` (type: `boolean`): Include full match statistics (possession, shots, passes, xG, etc.) for match records. Adds one request per match. ## `includeLineups` (type: `boolean`): Include starting XI, substitutes, formations and per-player ratings for match records. Adds one request per match. ## `includeIncidents` (type: `boolean`): Include goals, cards, substitutions and period scores for match records. Adds one request per match. ## `includeOdds` (type: `boolean`): Include pre-match betting odds markets for match records. Adds one request per match. ## `includeVotes` (type: `boolean`): Include the fan prediction poll for match records: how many fans voted home win / draw / away win, both-teams-to-score, and first-to-score. The community sentiment signal. Adds one lightweight request per match. ## `includeStandings` (type: `boolean`): Include the league table for tournament records. Adds one request per tournament. ## `includeSquad` (type: `boolean`): Include the full player squad for team records. Adds one request per team. ## `maxItems` (type: `integer`): The single cap: stop after this many entity records (0 = no limit). In Search mode it is spread fairly across your queries (each query returns up to 20, the SofaScore maximum). Add more queries to raise the realistic total. ## `proxy` (type: `object`): SofaScore accepts datacenter traffic from clean IPs; the scraper rotates connections automatically on rejection. Residential is optional and only needed under heavy load. ## Actor input object example ```json { "mode": "search", "searchQueries": [ "Real Madrid" ], "searchType": "all", "urls": [ "https://www.sofascore.com/team/football/real-madrid/2829" ], "sports": [ "football" ], "daysAhead": 0, "includeStatistics": true, "includeLineups": true, "includeIncidents": true, "includeOdds": false, "includeVotes": false, "includeStandings": true, "includeSquad": false, "maxItems": 20, "proxy": { "useApifyProxy": true } } ``` # Actor output Schema ## `overview` (type: `string`): No description # API You can run this Actor programmatically using our API. Below are code examples in JavaScript, Python, and CLI, as well as the OpenAPI specification and MCP server setup. ## JavaScript example ```javascript import { ApifyClient } from 'apify-client'; // Initialize the ApifyClient with your Apify API token // Replace the '' with your token const client = new ApifyClient({ token: '', }); // Prepare Actor input const input = { "searchQueries": [ "Real Madrid" ], "urls": [ "https://www.sofascore.com/team/football/real-madrid/2829" ], "date": "", "proxy": { "useApifyProxy": true } }; // Run the Actor and wait for it to finish const run = await client.actor("abotapi/sofascore-scraper").call(input); // Fetch and print Actor results from the run's dataset (if any) console.log('Results from dataset'); console.log(`💾 Check your data here: https://console.apify.com/storage/datasets/${run.defaultDatasetId}`); const { items } = await client.dataset(run.defaultDatasetId).listItems(); items.forEach((item) => { console.dir(item); }); // 📚 Want to learn more 📖? Go to → https://docs.apify.com/api/client/js/docs ``` ## Python example ```python from apify_client import ApifyClient # Initialize the ApifyClient with your Apify API token # Replace '' with your token. client = ApifyClient("") # Prepare the Actor input run_input = { "searchQueries": ["Real Madrid"], "urls": ["https://www.sofascore.com/team/football/real-madrid/2829"], "date": "", "proxy": { "useApifyProxy": True }, } # Run the Actor and wait for it to finish run = client.actor("abotapi/sofascore-scraper").call(run_input=run_input) # Fetch and print Actor results from the run's dataset (if there are any) print("💾 Check your data here: https://console.apify.com/storage/datasets/" + run["defaultDatasetId"]) for item in client.dataset(run["defaultDatasetId"]).iterate_items(): print(item) # 📚 Want to learn more 📖? Go to → https://docs.apify.com/api/client/python/docs/quick-start ``` ## CLI example ```bash echo '{ "searchQueries": [ "Real Madrid" ], "urls": [ "https://www.sofascore.com/team/football/real-madrid/2829" ], "date": "", "proxy": { "useApifyProxy": true } }' | apify call abotapi/sofascore-scraper --silent --output-dataset ``` ## MCP server setup ```json { "mcpServers": { "apify": { "command": "npx", "args": [ "mcp-remote", "https://mcp.apify.com/?tools=abotapi/sofascore-scraper", "--header", "Authorization: Bearer " ] } } } ``` ## OpenAPI specification ```json { "openapi": "3.0.1", "info": { "title": "SofaScore Scraper ⚽ Live Scores | Teams | Players | Fixtures", "description": "From $1/1K. Pull structured sports data from SofaScore across football, basketball, tennis, and 20+ sports. Search by keyword, paste URLs, fetch live matches, or download fixtures by date. Returns scores, stats, lineups, incidents, odds, teams, players, tournaments, and more.", "version": "1.0", "x-build-id": "gjqFiteOJoOFWLbQA" }, "servers": [ { "url": "https://api.apify.com/v2" } ], "paths": { "/acts/abotapi~sofascore-scraper/run-sync-get-dataset-items": { "post": { "operationId": "run-sync-get-dataset-items-abotapi-sofascore-scraper", "x-openai-isConsequential": false, "summary": "Executes an Actor, waits for its completion, and returns Actor's dataset items in response.", "tags": [ "Run Actor" ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/inputSchema" } } } }, "parameters": [ { "name": "token", "in": "query", "required": true, "schema": { "type": "string" }, "description": "Enter your Apify token here" } ], "responses": { "200": { "description": "OK" } } } }, "/acts/abotapi~sofascore-scraper/runs": { "post": { "operationId": "runs-sync-abotapi-sofascore-scraper", "x-openai-isConsequential": false, "summary": "Executes an Actor and returns information about the initiated run in response.", "tags": [ "Run Actor" ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/inputSchema" } } } }, "parameters": [ { "name": "token", "in": "query", "required": true, "schema": { "type": "string" }, "description": "Enter your Apify token here" } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/runsResponseSchema" } } } } } } }, "/acts/abotapi~sofascore-scraper/run-sync": { "post": { "operationId": "run-sync-abotapi-sofascore-scraper", "x-openai-isConsequential": false, "summary": "Executes an Actor, waits for completion, and returns the OUTPUT from Key-value store in response.", "tags": [ "Run Actor" ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/inputSchema" } } } }, "parameters": [ { "name": "token", "in": "query", "required": true, "schema": { "type": "string" }, "description": "Enter your Apify token here" } ], "responses": { "200": { "description": "OK" } } } } }, "components": { "schemas": { "inputSchema": { "type": "object", "required": [ "mode" ], "properties": { "mode": { "title": "Mode", "enum": [ "search", "url", "live", "scheduled" ], "type": "string", "description": "How to discover what to scrape. SEARCH looks up teams/players/tournaments/matches by keyword. URL takes SofaScore links you paste. LIVE pulls every in-play match for the chosen sports. SCHEDULED pulls all fixtures for a date.", "default": "search" }, "searchQueries": { "title": "Search queries", "type": "array", "description": "Keywords to look up: team, player, tournament, or match names. Each query resolves to the top matching entities, which are then scraped in full.", "items": { "type": "string" } }, "searchType": { "title": "Restrict search to type", "enum": [ "all", "team", "player", "tournament", "match" ], "type": "string", "description": "Limit which entity types a query resolves to. 'all' returns the best mix of teams, players, tournaments and matches.", "default": "all" }, "urls": { "title": "SofaScore URLs", "type": "array", "description": "Paste SofaScore links: match, team, player, or tournament pages. Match links must include the numeric id (the part after #id: in the address bar, or an /event/ link). Team/player/tournament links use the trailing numeric id.", "items": { "type": "string" } }, "sports": { "title": "Sports", "type": "array", "description": "Which sports to pull for Live and Scheduled modes.", "items": { "type": "string", "enum": [ "football", "basketball", "tennis", "ice-hockey", "american-football", "baseball", "handball", "volleyball", "cricket", "rugby", "table-tennis", "esports", "mma", "darts", "snooker", "futsal", "badminton", "waterpolo", "cycling", "motorsport" ], "enumTitles": [ "Football", "Basketball", "Tennis", "Ice Hockey", "American Football", "Baseball", "Handball", "Volleyball", "Cricket", "Rugby", "Table Tennis", "Esports", "MMA", "Darts", "Snooker", "Futsal", "Badminton", "Water Polo", "Cycling", "Motorsport" ] }, "default": [ "football" ] }, "date": { "title": "Date (Scheduled mode)", "type": "string", "description": "Day to pull fixtures for, in YYYY-MM-DD. Leave blank to use today (UTC)." }, "daysAhead": { "title": "Extra days", "minimum": 0, "maximum": 14, "type": "integer", "description": "Also pull fixtures for this many days after the chosen date. 0 = just the one day.", "default": 0 }, "includeStatistics": { "title": "Match statistics", "type": "boolean", "description": "Include full match statistics (possession, shots, passes, xG, etc.) for match records. Adds one request per match.", "default": true }, "includeLineups": { "title": "Match lineups", "type": "boolean", "description": "Include starting XI, substitutes, formations and per-player ratings for match records. Adds one request per match.", "default": true }, "includeIncidents": { "title": "Match incidents", "type": "boolean", "description": "Include goals, cards, substitutions and period scores for match records. Adds one request per match.", "default": true }, "includeOdds": { "title": "Match odds", "type": "boolean", "description": "Include pre-match betting odds markets for match records. Adds one request per match.", "default": false }, "includeVotes": { "title": "Fan votes (reviews)", "type": "boolean", "description": "Include the fan prediction poll for match records: how many fans voted home win / draw / away win, both-teams-to-score, and first-to-score. The community sentiment signal. Adds one lightweight request per match.", "default": false }, "includeStandings": { "title": "Tournament standings", "type": "boolean", "description": "Include the league table for tournament records. Adds one request per tournament.", "default": true }, "includeSquad": { "title": "Team squad", "type": "boolean", "description": "Include the full player squad for team records. Adds one request per team.", "default": false }, "maxItems": { "title": "Max items", "minimum": 0, "type": "integer", "description": "The single cap: stop after this many entity records (0 = no limit). In Search mode it is spread fairly across your queries (each query returns up to 20, the SofaScore maximum). Add more queries to raise the realistic total.", "default": 20 }, "proxy": { "title": "Proxy", "type": "object", "description": "SofaScore accepts datacenter traffic from clean IPs; the scraper rotates connections automatically on rejection. Residential is optional and only needed under heavy load.", "default": { "useApifyProxy": true } } } }, "runsResponseSchema": { "type": "object", "properties": { "data": { "type": "object", "properties": { "id": { "type": "string" }, "actId": { "type": "string" }, "userId": { "type": "string" }, "startedAt": { "type": "string", "format": "date-time", "example": "2025-01-08T00:00:00.000Z" }, "finishedAt": { "type": "string", "format": "date-time", "example": "2025-01-08T00:00:00.000Z" }, "status": { "type": "string", "example": "READY" }, "meta": { "type": "object", "properties": { "origin": { "type": "string", "example": "API" }, "userAgent": { "type": "string" } } }, "stats": { "type": "object", "properties": { "inputBodyLen": { "type": "integer", "example": 2000 }, "rebootCount": { "type": "integer", "example": 0 }, "restartCount": { "type": "integer", "example": 0 }, "resurrectCount": { "type": "integer", "example": 0 }, "computeUnits": { "type": "integer", "example": 0 } } }, "options": { "type": "object", "properties": { "build": { "type": "string", "example": "latest" }, "timeoutSecs": { "type": "integer", "example": 300 }, "memoryMbytes": { "type": "integer", "example": 1024 }, "diskMbytes": { "type": "integer", "example": 2048 } } }, "buildId": { "type": "string" }, "defaultKeyValueStoreId": { "type": "string" }, "defaultDatasetId": { "type": "string" }, "defaultRequestQueueId": { "type": "string" }, "buildNumber": { "type": "string", "example": "1.0.0" }, "containerUrl": { "type": "string" }, "usage": { "type": "object", "properties": { "ACTOR_COMPUTE_UNITS": { "type": "integer", "example": 0 }, "DATASET_READS": { "type": "integer", "example": 0 }, "DATASET_WRITES": { "type": "integer", "example": 0 }, "KEY_VALUE_STORE_READS": { "type": "integer", "example": 0 }, "KEY_VALUE_STORE_WRITES": { "type": "integer", "example": 1 }, "KEY_VALUE_STORE_LISTS": { "type": "integer", "example": 0 }, "REQUEST_QUEUE_READS": { "type": "integer", "example": 0 }, "REQUEST_QUEUE_WRITES": { "type": "integer", "example": 0 }, "DATA_TRANSFER_INTERNAL_GBYTES": { "type": "integer", "example": 0 }, "DATA_TRANSFER_EXTERNAL_GBYTES": { "type": "integer", "example": 0 }, "PROXY_RESIDENTIAL_TRANSFER_GBYTES": { "type": "integer", "example": 0 }, "PROXY_SERPS": { "type": "integer", "example": 0 } } }, "usageTotalUsd": { "type": "number", "example": 0.00005 }, "usageUsd": { "type": "object", "properties": { "ACTOR_COMPUTE_UNITS": { "type": "integer", "example": 0 }, "DATASET_READS": { "type": "integer", "example": 0 }, "DATASET_WRITES": { "type": "integer", "example": 0 }, "KEY_VALUE_STORE_READS": { "type": "integer", "example": 0 }, "KEY_VALUE_STORE_WRITES": { "type": "number", "example": 0.00005 }, "KEY_VALUE_STORE_LISTS": { "type": "integer", "example": 0 }, "REQUEST_QUEUE_READS": { "type": "integer", "example": 0 }, "REQUEST_QUEUE_WRITES": { "type": "integer", "example": 0 }, "DATA_TRANSFER_INTERNAL_GBYTES": { "type": "integer", "example": 0 }, "DATA_TRANSFER_EXTERNAL_GBYTES": { "type": "integer", "example": 0 }, "PROXY_RESIDENTIAL_TRANSFER_GBYTES": { "type": "integer", "example": 0 }, "PROXY_SERPS": { "type": "integer", "example": 0 } } } } } } } } } } ```