# SofaScore API Scraper (`rl1987/sofascore-api-scraper`) Actor

Scrape live scores, scheduled fixtures, match detail and search results directly from SofaScore's public backend API.

- **URL**: https://apify.com/rl1987/sofascore-api-scraper.md
- **Developed by:** [R.L.](https://apify.com/rl1987) (community)
- **Categories:** News
- **Stats:** 1 total users, 1 monthly users, 100.0% runs succeeded, 0 bookmarks
- **User rating**: No ratings yet

## Pricing

from $1.00 / 1,000 dataset rows

This Actor is paid per event and usage. You are charged both the fixed price for specific events and for Apify platform usage.

Learn more: https://docs.apify.com/platform/actors/running/actors-in-store#pay-per-event

## What's an Apify Actor?

Actors are web data automations that power AI and operations. They run on the Apify platform to scrape websites, process data, connect APIs, and automate workflows.
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.

- **AI agents and MCP clients** — the [Apify MCP server](https://docs.apify.com/integrations/mcp.md) at `https://mcp.apify.com` (remote, streamable HTTP, OAuth on first use).
- **Agentic workflows and local Actor development** — [Agent Skills](https://apify.com/.well-known/agent-skills/index.json) with the [Apify CLI](https://docs.apify.com/cli/docs.md): `npm install -g apify-cli`, then `apify login`.
- **JavaScript/TypeScript projects** — the official [JS/TS client](https://docs.apify.com/api/client/js/docs.md): `npm install apify-client`.
- **Python projects** — the official [Python client](https://docs.apify.com/api/client/python/docs.md): `pip install apify-client`.
- **Any other language** — 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

### What does SofaScore API Scraper do?

**SofaScore API Scraper** extracts live scores, scheduled fixtures, full match detail, and search results straight from [SofaScore](https://www.sofascore.com)'s own backend REST API -- the same one the official Android app talks to. It covers football, basketball, tennis, cricket, esports, motorsport, and every other sport SofaScore tracks. Because it hits the API directly instead of rendering pages, it's fast, cheap, and returns clean structured JSON rather than scraped HTML.

Run it on the Apify platform to get scheduling, an API for pulling results, webhook/integration support, and automatic dataset export -- no need to babysit a script.

### Why use SofaScore API Scraper?

- **Sports betting & odds research** -- pull live scores and fixtures on a schedule to feed models or dashboards.
- **Fantasy sports tools** -- player/team stats and match detail for lineup or projection tools.
- **Media & content sites** -- auto-populate scoreboards and fixture lists.
- **Data analysis** -- build historical match datasets by sweeping date ranges.

### How to use SofaScore API Scraper

1. Click **Try for free** (or **Start**) on the Actor page.
2. Pick a **Mode**: `live` events, `scheduled` events for a date range, `event_detail` for specific match IDs, or `search`.
3. Set the relevant fields (sport, date range, event IDs, or search query).
4. Click **Start** and wait for the run to finish.
5. Open the **Dataset** tab to view, export, or download results (JSON, CSV, Excel, HTML, and more).

### Input

| Field | Type | Description |
|---|---|---|
| `mode` | string | `live`, `scheduled`, `event_detail`, or `search` |
| `sport` | string | SofaScore sport slug, e.g. `football`, `basketball`, `tennis` (used by `live`/`scheduled`) |
| `dateFrom` / `dateTo` | string | `YYYY-MM-DD` range for `scheduled` mode (inclusive) |
| `maxPages` | integer | Max pages per day for `scheduled` mode (pagination is 1-indexed) |
| `eventIds` | array | Event IDs to fetch full detail for, in `event_detail` mode |
| `searchQuery` | string | Free-text query for `search` mode (team, player, tournament) |
| `fetchEventDetails` | boolean | For `live`/`scheduled`, fan out to full match detail per event (more requests) |
| `maxItems` | integer | Stop after this many dataset items (`0` = unlimited) |
| `requestDelaySecs` | number | Delay between outgoing API calls |
| `proxyConfiguration` | object | Optional; SofaScore isn't IP rate-limited, so this is rarely needed |

See the **Input** tab for the full schema with defaults.

### Output

Output is flattened -- one level deep, no nested objects -- so it drops straight into CSV/Excel without post-processing.

Example dataset item for a live/scheduled event:

```json
{
    "kind": "event",
    "id": 16860578,
    "slug": "port-city-fc-golden-warriors-fc",
    "startTimestamp": 1755532800,
    "sport": "football",
    "tournament": "NPSL",
    "category": "USA",
    "country": "USA",
    "homeTeamId": 452321,
    "homeTeam": "Port City FC",
    "awayTeamId": 452322,
    "awayTeam": "Golden Warriors FC",
    "homeScore": 1,
    "awayScore": 0,
    "statusType": "inprogress",
    "statusDescription": "2nd half"
}
```

You can download the dataset in various formats such as JSON, HTML, CSV, or Excel.

### Data table

| Field | Description |
|---|---|
| `kind` | `event`, `event_detail`, or `search_result` -- identifies the record shape |
| `id` / `slug` | SofaScore event or entity ID and URL slug |
| `startTimestamp` | Unix start time |
| `sport`, `tournament`, `uniqueTournament`, `category`, `country`, `round`, `roundName` | Competition context |
| `homeTeamId` / `homeTeam` / `homeTeamCountry`, `awayTeamId` / `awayTeam` / `awayTeamCountry` | Team info |
| `homeScore` / `awayScore` | Current score |
| `statusCode` / `statusType` / `statusDescription` | Match status (not started / in progress / finished, period) |
| `venue` / `venueCity` / `referee` | Present on `event_detail` items when SofaScore has the data |
| `resultType`, `score`, `entityId`, `entityName`, `entitySlug`, `entityType`, `teamId`, `teamName` | `search_result` items only -- matched team/player/tournament and its parent team |

### Pricing / Cost estimation

This Actor uses **pay-per-event** pricing: **$1 per 1,000 dataset rows** ($0.001/row), charged only for rows actually written to the dataset (plus standard Apify platform usage). Turning on `fetchEventDetails` or sweeping wide date ranges produces more rows -- use `maxItems` and `maxPages` to keep spend predictable, or set a max run charge cap in the run's advanced options.

### Tips or Advanced options

- Leave `fetchEventDetails` off for a fast overview pass; turn it on only when you need venue/referee-level detail.
- For historical sweeps, narrow `dateFrom`/`dateTo` and set `maxItems` to avoid runaway runs.
- `page=1` is the first page of scheduled events for a given date -- `page=0` always returns an empty list (undocumented API quirk).
- Schedule this Actor to run daily/hourly via the Apify **Schedules** feature for always-fresh data.

### FAQ, disclaimers, and support

This Actor calls SofaScore's public, unauthenticated backend API (no login, no key required, `access-control-allow-origin: *`). It's provided for research and legitimate data-integration use; you're responsible for complying with SofaScore's Terms of Service in your jurisdiction and use case. SofaScore's own FAQ states they don't officially license API access due to data-provider agreements, so treat this as an unofficial integration, not a supported one.

**Current coverage:** live/scheduled events, single-event detail, and search. Lineups, in-match statistics (shots, possession, xG), incidents (goals/cards/subs timeline), head-to-head history, league standings, odds, and team/player profile data are **not yet covered** -- betting, fantasy, and deep-analytics use cases that need those will require extending the Actor with additional modes.

Found a bug or need a custom field/endpoint added? Open an issue in the Actor's **Issues** tab, or reach out for a custom scraping solution.

# Actor input Schema

## `mode` (type: `string`):

What to scrape.

## `sport` (type: `string`):

SofaScore sport. Used by 'live' and 'scheduled' modes.

## `dateFrom` (type: `string`):

Start date for 'scheduled' mode. Defaults to today.

## `dateTo` (type: `string`):

End date for 'scheduled' mode, inclusive. Defaults to dateFrom.

## `maxPages` (type: `integer`):

Scheduled-events pagination is 1-indexed (page=1 is the first page). Scraper stops early once a page returns no events.

## `eventIds` (type: `array`):

SofaScore event IDs to fetch full detail for. Used by 'event\_detail' mode. Add one ID per line.

## `searchQuery` (type: `string`):

Free-text query (team, player, tournament). Used by 'search' mode.

## `fetchEventDetails` (type: `boolean`):

For 'live'/'scheduled' modes, fan out and fetch full match detail (GET /event/{id}) for every event found instead of pushing the list item as-is. Multiplies request count.

## `maxItems` (type: `integer`):

Stop after pushing this many dataset items. 0 = unlimited.

## `requestDelaySecs` (type: `number`):

Small delay between outgoing API calls to stay polite to Cloudflare-fronted api.sofascore.com.

## `proxyConfiguration` (type: `object`):

Cloudflare fronts api.sofascore.com and appears to block Apify's datacenter IP range outright, so residential proxy is enabled by default. You can disable it if running from an IP Cloudflare already trusts.

## Actor input object example

```json
{
  "mode": "live",
  "sport": "football",
  "maxPages": 3,
  "eventIds": [],
  "fetchEventDetails": false,
  "maxItems": 0,
  "requestDelaySecs": 0.3,
  "proxyConfiguration": {
    "useApifyProxy": true,
    "apifyProxyGroups": [
      "RESIDENTIAL"
    ]
  }
}
```

# Actor output Schema

## `results` (type: `string`):

Dataset rows produced by the run (events or search results, one flat row per item).

# 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 '<YOUR_API_TOKEN>' with your token
const client = new ApifyClient({
    token: '<YOUR_API_TOKEN>',
});

// Prepare Actor input
const input = {};

// Run the Actor and wait for it to finish
const run = await client.actor("rl1987/sofascore-api-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 '<YOUR_API_TOKEN>' with your token.
client = ApifyClient("<YOUR_API_TOKEN>")

# Prepare the Actor input
run_input = {}

# Run the Actor and wait for it to finish
run = client.actor("rl1987/sofascore-api-scraper").call(run_input=run_input)

# Fetch and print Actor results from the run's dataset (if there are any)
print(f"💾 Check your data here: https://console.apify.com/storage/datasets/{run.default_dataset_id}")
for item in client.dataset(run.default_dataset_id).iterate_items():
    print(item)

# 📚 Want to learn more 📖? Go to → https://docs.apify.com/api/client/python/docs/quick-start

```

## CLI example

```bash
echo '{}' |
apify call rl1987/sofascore-api-scraper --silent --output-dataset

```

## MCP server setup

```json
{
    "mcpServers": {
        "apify": {
            "type": "http",
            "url": "https://mcp.apify.com/?tools=fetch-actor-details,rl1987/sofascore-api-scraper"
        }
    }
}

```

The hosted server signs you in with OAuth on first connect, so no API token belongs in this config. Clients without OAuth support can send an `Authorization: Bearer <APIFY_API_TOKEN>` header instead, using a token from API & Integrations in Apify Console (https://console.apify.com/settings/integrations).

## OpenAPI specification

Download the OpenAPI definition: https://api.apify.com/v2/actors/62hJll1LuUdPyxpbG/builds/xnxe8U69dnoxmaZZ5/openapi.json