# Whoscored — 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.

> Search for players and teams, then dive deep into their performance metrics, match statistics, and detailed passing data to analyze football games and player abilities. Get comprehensive insights on team performance, individual player stats, and play-by-play event information to power your football analysis and decision-making.

**Category:** Sports | **Website:** [whoscored.com/](https://whoscored.com/) | **Docs:** [parse.bot/marketplace/16df779e-f6ee-4b02-a8c5-9f5efc49f125/whoscored-com-api](https://parse.bot/marketplace/16df779e-f6ee-4b02-a8c5-9f5efc49f125/whoscored-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-whoscored-com-api-16df779e/`
**Auth:** `Authorization: Bearer <LOCUS_API_KEY>`

## Endpoints

### get_match_events

Retrieve all match centre events for a specific completed match, including passes with origin (x, y) and destination (endX, endY) coordinates, player info, event type, outcome, and qualifiers. The match_id is obtainable from match links on tournament pages. Only completed matches with Opta data will return events; future or non-Opta matches return an upstream error. The response contains all events in a single request (typically 1000-2000 events per match). Page size is ~1.5MB due to embedded data.

**Estimated cost:** Metered

| Field | Type | Required | Description |
|-------|------|----------|-------------|
| `match_id` | string | Yes | Numeric match ID from WhoScored (found in match page URLs, e.g. 1729441 for Tottenham vs Man City) |

```bash
curl -X POST https://api.paywithlocus.com/api/wrapped/parse-whoscored-com-api-16df779e/get_match_events \
  -H "Authorization: Bearer YOUR_LOCUS_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"match_id":"<string>"}'
```

### get_player_stats

Retrieve seasonal statistics for a specific player across all tournaments they have participated in. Returns per-season records including rating, goals, appearances, assists, pass success rate, shots per game, and more. The player_id is obtainable from the search endpoint.

**Estimated cost:** Metered

| Field | Type | Required | Description |
|-------|------|----------|-------------|
| `player_id` | string | Yes | Numeric player ID from WhoScored (obtainable from search endpoint results) |

```bash
curl -X POST https://api.paywithlocus.com/api/wrapped/parse-whoscored-com-api-16df779e/get_player_stats \
  -H "Authorization: Bearer YOUR_LOCUS_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"player_id":"<string>"}'
```

### get_team_stats

Retrieve seasonal statistics for a specific team across all tournaments it participates in. Returns per-tournament records including rating, goals, possession percentage, pass success rate, shots per game, and cards. The team_id is obtainable from the search endpoint.

**Estimated cost:** Metered

| Field | Type | Required | Description |
|-------|------|----------|-------------|
| `team_id` | string | Yes | Numeric team ID from WhoScored (obtainable from search endpoint results) |

```bash
curl -X POST https://api.paywithlocus.com/api/wrapped/parse-whoscored-com-api-16df779e/get_team_stats \
  -H "Authorization: Bearer YOUR_LOCUS_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"team_id":"<string>"}'
```

### list_matches

Retrieve all fixtures and results for a specific team. For current active seasons, data comes from the team's fixtures page in a single request. When a season parameter is provided and matches for that season are archived (e.g. a completed league season), the endpoint fetches archived tournament data by iterating through monthly fixture feeds, resulting in ~14 requests total. Each match includes match_id (usable with get_match_events), date, kickoff time, home/away teams with IDs, score (null for upcoming), status, tournament name, and season. Results are chronologically ordered across all tournaments the team participates in.

**Estimated cost:** Metered

| Field | Type | Required | Description |
|-------|------|----------|-------------|
| `season` | string | No | Season to filter by in YYYY/YYYY format (e.g. '2024/2025'). When omitted, returns matches from all current seasons. |
| `team_id` | string | Yes | Numeric team ID from WhoScored (obtainable from search endpoint results) |

```bash
curl -X POST https://api.paywithlocus.com/api/wrapped/parse-whoscored-com-api-16df779e/list_matches \
  -H "Authorization: Bearer YOUR_LOCUS_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"season":"<string>","team_id":"<string>"}'
```

### search

Full-text search over WhoScored's player and team database. Returns matching players (with IDs, slugs, current team, age) and teams (with IDs, slugs, country). A query that matches only players returns an empty teams array and vice versa. Results are unordered and unpaginated — the server returns all matches in a single response.

**Estimated cost:** Metered

| Field | Type | Required | Description |
|-------|------|----------|-------------|
| `query` | string | Yes | Search keyword (player or team name) |

```bash
curl -X POST https://api.paywithlocus.com/api/wrapped/parse-whoscored-com-api-16df779e/search \
  -H "Authorization: Bearer YOUR_LOCUS_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"query":"<string>"}'
```