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

> Get live football scores, detailed match results, and comprehensive league statistics across multiple competitions. Access player and team performance data, browse upcoming fixtures by date, and dive into in-depth analytics for your favorite leagues and matches.

**Category:** Sports | **Website:** [fotmob.com/](https://fotmob.com/) | **Docs:** [parse.bot/marketplace/d2378e4b-52ce-4f58-bd5d-d500dfc9da27/fotmob-com-api](https://parse.bot/marketplace/d2378e4b-52ce-4f58-bd5d-d500dfc9da27/fotmob-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-fotmob-com-api-d2378e4b/`
**Auth:** `Authorization: Bearer <LOCUS_API_KEY>`

## Endpoints

### get_compact_matches_by_date

Compact match schedule for a date, optimized for low-memory clients (sub-12 KB). Returns every FotMob match for the given date with minimal short-keyed fields: numeric IDs, team names, scores (or -1 before kickoff), status, and live minute. No nested objects, logos, URLs, or metadata.

**Estimated cost:** Metered

| Field | Type | Required | Description |
|-------|------|----------|-------------|
| `date` | string | Yes | Date in YYYYMMDD format (e.g. 20260714). |

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

### get_cup_players

Get all players who participated in a cup competition by aggregating lineup data across finished matches. Fetches the fixture list for the cup, then fetches match details for up to 25 of the most recent finished matches (later rounds prioritized), and aggregates unique players with cumulative stats. Returns players sorted by appearances (descending), then goals (descending). Each request makes up to 26 upstream calls (1 for fixtures + up to 25 for match details). Best suited for cup competitions with knockout rounds.

**Estimated cost:** Metered

| Field | Type | Required | Description |
|-------|------|----------|-------------|
| `league_id` | string | Yes | League/cup ID (e.g. 133 for EFL Cup, 132 for FA Cup, 73 for Europa League). Obtainable from get_leagues. |
| `season` | string | No | Season in YYYY/YYYY format (e.g. 2024/2025). Omitting returns the current/latest season. |

```bash
curl -X POST https://api.paywithlocus.com/api/wrapped/parse-fotmob-com-api-d2378e4b/get_cup_players \
  -H "Authorization: Bearer YOUR_LOCUS_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"league_id":"<string>","season":"<string>"}'
```

### get_historical_match_results

Get detailed historical match results for a league season, with optional team filter. For each finished match, returns scores (HT/FT/ET), penalty shootout details, goals with scorers and assists, cards, substitutions, team stats (possession, shots, xG, passes, etc.), venue, and referee. Fetches individual match details for each fixture in the season, so filtering by team_id is recommended for faster responses.

**Estimated cost:** Metered

| Field | Type | Required | Description |
|-------|------|----------|-------------|
| `league_id` | string | Yes | League ID (e.g. 47 for Premier League). Obtainable from get_leagues. |
| `season` | string | No | Season in YYYY/YYYY format (e.g. 2024/2025). Omitting returns the current/latest season. |
| `team_id` | string | No | Numeric FotMob team ID to filter results to only matches involving this team. Obtainable from get_matches_by_date or get_league_details. |

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

### get_league_details

Get detailed league information including standings table (with all/home/away/form/xg breakdowns), fixtures, transfers, and available seasons. The standings table shows team positions, points, wins, draws, losses, and goal differences.

**Estimated cost:** Metered

| Field | Type | Required | Description |
|-------|------|----------|-------------|
| `league_id` | string | Yes | League ID (e.g. 47 for Premier League, 87 for La Liga, 54 for Bundesliga, 53 for Ligue 1, 55 for Serie A). Obtainable from get_leagues. |
| `season` | string | No | Season in YYYY/YYYY format (e.g. 2024/2025). Omitting returns the current season. |

```bash
curl -X POST https://api.paywithlocus.com/api/wrapped/parse-fotmob-com-api-d2378e4b/get_league_details \
  -H "Authorization: Bearer YOUR_LOCUS_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"league_id":"<string>","season":"<string>"}'
```

### get_league_players

Get all players from every team in a league for a specific season with biographical details. For historical seasons, uses league-wide stats data for performance metrics (goals, assists, rating, minutes played, matches played) and enriches each player with biographical data (age, date_of_birth, nationality, height, shirt_number, market_value) from team squad and individual player endpoints. For the current/latest season, fetches the full squad roster per team with biographical details and coaching staff. Historical seasons make approximately 26-56 upstream requests (5 stat files + 20 squad fetches + up to 30 individual player fetches for players who left their club); the current season makes one request per team (typically 20-21 requests total).

**Estimated cost:** Metered

| Field | Type | Required | Description |
|-------|------|----------|-------------|
| `league_id` | string | Yes | League ID (e.g. 47 for Premier League). Obtainable from get_leagues. |
| `season` | string | No | Season in YYYY/YYYY format (e.g. 2024/2025). Omitting returns the current/latest season. |

```bash
curl -X POST https://api.paywithlocus.com/api/wrapped/parse-fotmob-com-api-d2378e4b/get_league_players \
  -H "Authorization: Bearer YOUR_LOCUS_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"league_id":"<string>","season":"<string>"}'
```

### get_league_stats

Get season-wide player and team statistics for a league. Returns top scorers, assists, expected goals, clean sheets, and other statistical categories alongside the league standings table.

**Estimated cost:** Metered

| Field | Type | Required | Description |
|-------|------|----------|-------------|
| `league_id` | string | Yes | League ID (e.g. 47 for Premier League, 87 for La Liga, 54 for Bundesliga, 53 for Ligue 1, 55 for Serie A). Obtainable from get_leagues. |
| `season` | string | No | Season in YYYY/YYYY format (e.g. 2024/2025). Omitting returns the current season. |

```bash
curl -X POST https://api.paywithlocus.com/api/wrapped/parse-fotmob-com-api-d2378e4b/get_league_stats \
  -H "Authorization: Bearer YOUR_LOCUS_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"league_id":"<string>","season":"<string>"}'
```

### get_leagues

List all supported leagues with their IDs and metadata. Returns popular leagues, country-specific leagues, and international league groups. Use league IDs from this endpoint as input to get_league_details and get_league_stats.

**Estimated cost:** Metered

_No parameters required._

```bash
curl -X POST https://api.paywithlocus.com/api/wrapped/parse-fotmob-com-api-d2378e4b/get_leagues \
  -H "Authorization: Bearer YOUR_LOCUS_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{}'
```

### get_match_analytics

Get advanced match analytics in a single request: team-level xG breakdown (open-play, set-play, non-penalty, xGOT) split by full match, first half, and second half; per-player progressive/final-third passing and defensive contribution stats for every player who featured; and a full shotmap with per-shot xG, xGOT, pitch coordinates, situation, and player/team attribution. Requires a completed or in-progress match with tracking data; future or data-sparse matches may return null xG values.

**Estimated cost:** Metered

| Field | Type | Required | Description |
|-------|------|----------|-------------|
| `match_id` | string | Yes | Match ID. Obtainable from get_matches_by_date or get_league_details fixtures. |

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

### get_match_details

Get comprehensive match details including lineups, team stats, player performance stats, events (goals, cards, substitutions), head-to-head data, and momentum. The match must have started or been completed; future scheduled matches may not have full details available.

**Estimated cost:** Metered

| Field | Type | Required | Description |
|-------|------|----------|-------------|
| `match_id` | string | Yes | Match ID. Obtainable from get_matches_by_date or get_league_details fixtures. |

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

### get_match_lineup

Get full match lineup and detailed per-player statistics for a completed or in-progress match. Returns starting XI and substitutes who entered the field for both teams, with comprehensive stats (rating, goals, assists, shots, passes, duels, defensive actions, xG/xA) and positional heatmap coordinates. Also returns match events (goals, cards, substitutions) and a bench array of unused substitutes who were named in the matchday squad but never entered the field. Heatmap data is fetched from a secondary endpoint and may be null for players without tracking data.

**Estimated cost:** Metered

| Field | Type | Required | Description |
|-------|------|----------|-------------|
| `match_id` | string | Yes | Match ID. Obtainable from get_matches_by_date or get_league_details fixtures. |

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

### get_match_xg

Get expected goals (xG) breakdown for a match, including set-piece xG, open-play xG, non-penalty xG, and xG on target (xGOT) for both teams. Returns values split by full match, first half, and second half. Requires a single upstream request to the match details endpoint. xG data is only available for matches that have started or finished and have xG coverage; values may be null for matches without tracking data.

**Estimated cost:** Metered

| Field | Type | Required | Description |
|-------|------|----------|-------------|
| `match_id` | string | Yes | Match ID. Obtainable from get_matches_by_date or get_league_details fixtures. |

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

### get_matches_by_date

Get all matches for a specific date, including live scores and statuses. Returns matches grouped by league. Each match includes home/away teams, scores, status (started/finished/cancelled), and timing information.

**Estimated cost:** Metered

| Field | Type | Required | Description |
|-------|------|----------|-------------|
| `date` | string | Yes | Date in YYYYMMDD format (e.g. 20260610). |

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

### get_player_match_stats

Get a game-by-game match log for a player from FotMob's recent matches data. Returns up to 60 of the player's most recent matches with date, competition, opponent, home/away, starting status, minutes, rating, goals, assists, and cards. Optional filters by season date range and league_id. A single upstream request. Advanced per-match metrics beyond goals/assists/rating are not available in this endpoint; use get_match_lineup for full per-player stats in a specific match.

**Estimated cost:** Metered

| Field | Type | Required | Description |
|-------|------|----------|-------------|
| `league_id` | string | No | Numeric league/competition ID to filter matches to a single competition. Obtainable from get_leagues or get_player_profile stat_seasons. |
| `player_id` | string | Yes | Numeric FotMob player ID. Obtainable from search_players or get_player_profile. |
| `season` | string | No | Season in YYYY/YYYY format (e.g. '2025/2026'). Filters matches to those within the season's date range. Omitting returns all available recent matches (up to 60). |

```bash
curl -X POST https://api.paywithlocus.com/api/wrapped/parse-fotmob-com-api-d2378e4b/get_player_match_stats \
  -H "Authorization: Bearer YOUR_LOCUS_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"league_id":"<string>","player_id":"<string>","season":"<string>"}'
```

### get_player_profile

Get a full player profile from FotMob including biographical details, position, current club, contract information, market value, and season rating. Also returns the list of available stat_seasons with their tournament entries, which can be passed to get_player_season_stats. A single upstream request.

**Estimated cost:** Metered

| Field | Type | Required | Description |
|-------|------|----------|-------------|
| `player_id` | string | Yes | Numeric FotMob player ID. Obtainable from search_players, get_match_lineup, or get_league_players. |

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

### get_player_season_stats

Get season-aggregated statistics for a player broken down by competition. Returns totals and per-90 values for goals, assists, xG, xA, passes, chances created, dribbles, duels, recoveries, tackles, interceptions, and more. Makes one request per competition in the selected season (typically 2-6 upstream requests total). Metrics not tracked for a given competition return null.

**Estimated cost:** Metered

| Field | Type | Required | Description |
|-------|------|----------|-------------|
| `player_id` | string | Yes | Numeric FotMob player ID. Obtainable from search_players or get_player_profile. |
| `season` | string | No | Season name exactly as returned in get_player_profile stat_seasons (e.g. '2024/2025', '2026'). Omitting returns the most recent season. |

```bash
curl -X POST https://api.paywithlocus.com/api/wrapped/parse-fotmob-com-api-d2378e4b/get_player_season_stats \
  -H "Authorization: Bearer YOUR_LOCUS_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"player_id":"<string>","season":"<string>"}'
```

### get_player_traits

Get a player's traits and positional characteristics from FotMob in a single upstream request. Returns trait comparisons (statistical percentile values compared to positional peers) and the player's positional profile. Traits may be null when the player has no recent competitive data. Lightweight alternative to get_player_profile when only playing-style descriptors are needed.

**Estimated cost:** Metered

| Field | Type | Required | Description |
|-------|------|----------|-------------|
| `player_id` | string | Yes | Numeric FotMob player ID. Obtainable from get_match_lineup or get_league_players. |

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

### get_team_fixtures

Get fixtures for a team including past results and upcoming scheduled matches. Returns match IDs, opponent details, home/away indicator, UTC time, league name, and match status. For the current/latest season (omitting season or passing the current season), returns fixtures from mid-season onward. For past seasons, paginates backwards through the team's fixture history to collect all matches within that season's date range (July of start year through July of end year). Makes up to 10 paginated requests for past seasons.

**Estimated cost:** Metered

| Field | Type | Required | Description |
|-------|------|----------|-------------|
| `season` | string | No | Season in YYYY/YYYY format (e.g. 2024/2025). Omitting returns the current/latest season. |
| `team_id` | string | Yes | Numeric FotMob team ID. Obtainable from get_matches_by_date or get_league_details. |

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

### search_players

Search FotMob for players by name. Returns matching players with their IDs, current team, and page URL. This is the entry point for resolving a player name to a FotMob player_id. Results are ranked by FotMob's relevance score. A single upstream request.

**Estimated cost:** Metered

| Field | Type | Required | Description |
|-------|------|----------|-------------|
| `limit` | integer | No | Maximum number of results to return. Omitting returns all matches from FotMob's suggestion list (typically 3-5). |
| `query` | string | Yes | Player name search term (e.g. 'Salah', 'Messi'). |

```bash
curl -X POST https://api.paywithlocus.com/api/wrapped/parse-fotmob-com-api-d2378e4b/search_players \
  -H "Authorization: Bearer YOUR_LOCUS_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"limit":"<integer>","query":"<string>"}'
```