# Sofascore — Wrapped API

> **You are on:** `https://api.paywithlocus.com/api` | [llms.txt](https://paywithlocus.com/llms.txt) | [docs](https://docs.paywithlocus.com)
>
> Locus runs on multiple environments -- make sure every URL you call matches your expected environment.
> | Environment | Landing | API | Docs |
> |---|---|---|---|
> | Production | paywithlocus.com | api.paywithlocus.com | docs.paywithlocus.com |
> | Beta | beta.paywithlocus.com | api.beta.paywithlocus.com | docs.paywithlocus.com |
> | Stage | stage.paywithlocus.com | api.stage.paywithlocus.com | docs.paywithlocus.com |
>
> If the API URL above doesn't match your expected environment, re-fetch this file from the correct domain.

> Access head-to-head statistics and streaks for sporting events across a wide range of sports. Retrieve daily scheduled events, detailed H2H metrics (win rates, unbeaten records, draw rates, manager duels), and event fun facts. Filter and rank H2H streak metrics by configurable percentage thresholds to identify historically consistent patterns between any two teams.

**Category:** Sports | **Website:** [www.sofascore.com/](https://www.sofascore.com/) | **Docs:** [parse.bot/marketplace/ffacae0a-ac86-425e-afa4-649c6d32e4e2/sofascore-com-api](https://parse.bot/marketplace/ffacae0a-ac86-425e-afa4-649c6d32e4e2/sofascore-com-api)

Pay-per-use API proxy. Each call is automatically billed to your wallet in USDC.

## Access

**Base URL:** `https://api.paywithlocus.com/api/wrapped/parse-sofascore-com-api-ffacae0a/`
**Auth:** `Authorization: Bearer <LOCUS_API_KEY>`

## Endpoints

### get_daily_events

Get all scheduled sporting events for a given date across specified sports. Returns event details including teams, tournament, scores, and status. Paginates internally across sport categories. Each event carries an event_id usable as input to get_event_h2h, get_event_details, and get_event_fun_facts.

**Estimated cost:** Metered

| Field | Type | Required | Description |
|-------|------|----------|-------------|
| `date` | string | No | Date in YYYY-MM-DD format. Omitting uses today's date. |
| `limit` | integer | No | Maximum total events to return across all sports (0 = no limit). |
| `sports` | string | No | Comma-separated sports: football,basketball,tennis,ice-hockey,baseball,handball,rugby,american-football,volleyball,cricket,esports. Omitting queries all sports. |

```bash
curl -X POST https://api.paywithlocus.com/api/wrapped/parse-sofascore-com-api-ffacae0a/get_daily_events \
  -H "Authorization: Bearer YOUR_LOCUS_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"date":"<string>","limit":"<integer>","sports":"<string>"}'
```

### get_event_details

Get detailed information about a specific event including teams, scores, status, tournament, season, and round info. Score structure varies by sport (e.g. football has current/display/period scores). Requires a valid numeric event_id.

**Estimated cost:** Metered

| Field | Type | Required | Description |
|-------|------|----------|-------------|
| `event_id` | string | Yes | Sofascore event ID (numeric). Obtainable from get_daily_events results. |

```bash
curl -X POST https://api.paywithlocus.com/api/wrapped/parse-sofascore-com-api-ffacae0a/get_event_details \
  -H "Authorization: Bearer YOUR_LOCUS_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"event_id":"<string>"}'
```

### get_event_fun_facts

Get fun facts and detailed H2H insights for a specific event. Primarily available for football events; non-football events typically return input_not_found. Each fact has text and a highlighted flag indicating editorial prominence.

**Estimated cost:** Metered

| Field | Type | Required | Description |
|-------|------|----------|-------------|
| `event_id` | string | Yes | Sofascore event ID (numeric). Obtainable from get_daily_events results. |

```bash
curl -X POST https://api.paywithlocus.com/api/wrapped/parse-sofascore-com-api-ffacae0a/get_event_fun_facts \
  -H "Authorization: Bearer YOUR_LOCUS_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"event_id":"<string>"}'
```

### get_event_h2h

Get comprehensive head-to-head statistics for a specific event, including team duel summary (wins/draws/total), manager duel, pregame form, and fun facts. Requires a valid numeric event_id from get_daily_events.

**Estimated cost:** Metered

| Field | Type | Required | Description |
|-------|------|----------|-------------|
| `event_id` | string | Yes | Sofascore event ID (numeric). Obtainable from get_daily_events results. |

```bash
curl -X POST https://api.paywithlocus.com/api/wrapped/parse-sofascore-com-api-ffacae0a/get_event_h2h \
  -H "Authorization: Bearer YOUR_LOCUS_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"event_id":"<string>"}'
```

### get_event_incidents

Returns the full in-match incidents timeline for a finished football match: goals (with scorer, minute, penalty/own-goal flag, running score after each), cards (with player, minute, colour, team), substitutions, and VAR decisions. Sorted chronologically. Incidents are available only for matches that have started or finished.

**Estimated cost:** Metered

| Field | Type | Required | Description |
|-------|------|----------|-------------|
| `event_id` | string | Yes | Sofascore event ID (numeric). Obtainable from get_daily_events results. |

```bash
curl -X POST https://api.paywithlocus.com/api/wrapped/parse-sofascore-com-api-ffacae0a/get_event_incidents \
  -H "Authorization: Bearer YOUR_LOCUS_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"event_id":"<string>"}'
```

### get_event_odds

Get pre-match betting odds for a specific event. Returns available betting markets (match winner, set winner, total games, etc.) with fractional odds for each choice. Works for tennis, football, and other sports. Odds availability depends on the bookmaker coverage for the event.

**Estimated cost:** Metered

| Field | Type | Required | Description |
|-------|------|----------|-------------|
| `event_id` | string | Yes | Sofascore event ID (numeric). Obtainable from get_tennis_fixtures or get_daily_events results. |

```bash
curl -X POST https://api.paywithlocus.com/api/wrapped/parse-sofascore-com-api-ffacae0a/get_event_odds \
  -H "Authorization: Bearer YOUR_LOCUS_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"event_id":"<string>"}'
```

### get_event_statistics

Get comprehensive match statistics for a specific finished event covering match overview (possession, xG, shots, saves, corners, fouls, passes, tackles, free kicks, yellow cards, distance covered, sprints), shots breakdown (on target, off target, woodwork, blocked, inside/outside box), and attack metrics (big chances scored/missed, through balls, touches in opposition box, fouled in final third, offsides). Statistics availability varies by league; fields are null when unavailable.

**Estimated cost:** Metered

| Field | Type | Required | Description |
|-------|------|----------|-------------|
| `event_id` | string | Yes | Sofascore event ID (numeric). Obtainable from get_daily_events results. |

```bash
curl -X POST https://api.paywithlocus.com/api/wrapped/parse-sofascore-com-api-ffacae0a/get_event_statistics \
  -H "Authorization: Bearer YOUR_LOCUS_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"event_id":"<string>"}'
```

### get_h2h

Returns the most recent finished matches between two specified teams (up to 10, newest first). Paginates through team event history and filters for matches involving both teams. If the teams have never met, returns an empty list.

**Estimated cost:** Metered

| Field | Type | Required | Description |
|-------|------|----------|-------------|
| `opponent_id` | string | Yes | Numeric SofaScore team ID for the opponent team. |
| `team_id` | string | Yes | Numeric SofaScore team ID for the first team. |

```bash
curl -X POST https://api.paywithlocus.com/api/wrapped/parse-sofascore-com-api-ffacae0a/get_h2h \
  -H "Authorization: Bearer YOUR_LOCUS_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"opponent_id":"<string>","team_id":"<string>"}'
```

### get_h2h_streaks_ranked

Fetches all daily events across specified sports, extracts H2H statistics for each matchup, computes streak metrics (home win %, away win %, draw %, home unbeaten %, away unbeaten %, manager duel %), and returns only those streaks occurring between min_percentage and max_percentage of the time, ranked in descending order by percentage. Processing many events is slow; use max_events to cap.

**Estimated cost:** Metered

| Field | Type | Required | Description |
|-------|------|----------|-------------|
| `date` | string | No | Date in YYYY-MM-DD format. Omitting uses today's date. |
| `max_events` | integer | No | Maximum events to process (0 = all). |
| `max_percentage` | number | No | Maximum streak percentage threshold. |
| `min_meetings` | integer | No | Minimum number of historical meetings required for a matchup to be included. |
| `min_percentage` | number | No | Minimum streak percentage threshold. |
| `sports` | string | No | Comma-separated sports: football,basketball,tennis,ice-hockey,baseball,handball,rugby,american-football,volleyball,cricket,esports. Omitting queries all sports. |

```bash
curl -X POST https://api.paywithlocus.com/api/wrapped/parse-sofascore-com-api-ffacae0a/get_h2h_streaks_ranked \
  -H "Authorization: Bearer YOUR_LOCUS_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"date":"<string>","max_events":"<integer>","max_percentage":"<number>","min_meetings":"<integer>","min_percentage":"<number>","sports":"<string>"}'
```

### get_tennis_fixtures

Get tennis fixtures for a given date across ATP, WTA, and other tennis categories. Returns match details including players with current ATP/WTA rankings, seeds, tournament round, surface type, venue info, and match status/scores. Each fixture carries an event_id usable as input to get_event_odds, get_event_details, and other event endpoints. Makes multiple internal requests to collect all tournaments.

**Estimated cost:** Metered

| Field | Type | Required | Description |
|-------|------|----------|-------------|
| `category` | string | No | Filter by tennis category slug: atp, wta, itf-men, itf-women, etc. Omitting returns all tennis categories. |
| `date` | string | No | Date in YYYY-MM-DD format. Omitting uses today's date. |

```bash
curl -X POST https://api.paywithlocus.com/api/wrapped/parse-sofascore-com-api-ffacae0a/get_tennis_fixtures \
  -H "Authorization: Bearer YOUR_LOCUS_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"category":"<string>","date":"<string>"}'
```

### get_upcoming_match

Find the next scheduled (not yet finished) match between two specified teams. Paginates through the first team's upcoming events looking for the opponent. Returns match details when found, or available=false with a reason when no upcoming match exists.

**Estimated cost:** Metered

| Field | Type | Required | Description |
|-------|------|----------|-------------|
| `opponent_id` | string | Yes | Numeric SofaScore team ID for the opponent team. |
| `team_id` | string | Yes | Numeric SofaScore team ID for the first team. |

```bash
curl -X POST https://api.paywithlocus.com/api/wrapped/parse-sofascore-com-api-ffacae0a/get_upcoming_match \
  -H "Authorization: Bearer YOUR_LOCUS_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"opponent_id":"<string>","team_id":"<string>"}'
```