Skip to main content

​
Overview

The Fixture Model defines data structures for match/event data, including participants, statistics, and odds from multiple bookmakers.

​
FotMob Fixture Structure

​
Core Fixture Document

​
general.matchId
integer
required
Unique match ID
​
general.matchName
string
required
Match name (e.g., “Liverpool vs Man City”)
​
general.matchRound
string
Competition round
​
general.leagueId
integer
League/competition ID
​
general.leagueName
string
League name
​
general.parentLeagueId
integer
Parent league ID (for sub-competitions)

​
Header Object

​
header.teams
array
required
Array of team objects
[
  {
    "id": 8650,
    "name": "Liverpool",
    "score": 2
  },
  {
    "id": 8456,
    "name": "Manchester City",
    "score": 1
  }
]
​
header.status
object
required
Match status
{
  "started": true,
  "finished": true,
  "cancelled": false,
  "scoreStr": "2-1",
  "reason": {
    "short": "FT",
    "long": "Full-Time"
  },
  "startDateStr": "Mar 10, 16:30"
}

​
Statistics Content

​
content.stats.Periods.All.stats
array
Full match statistics
[
  {
    "title": "Possession (%)",
    "stats": ["48", "52"],
    "highlighted": "away",
    "type": "possession"
  },
  {
    "title": "Shots",
    "stats": ["15", "18"],
    "highlighted": "away",
    "type": "shots"
  },
  {
    "title": "Shots on target",
    "stats": ["6", "8"],
    "highlighted": "away",
    "type": "shotsOnTarget"
  }
]

​
Player Statistics

​
content.playerStats
object
Player performance statistics
{
  "homeTeam": [
    {
      "playerId": 118748,
      "name": {
        "firstName": "Mohamed",
        "lastName": "Salah",
        "fullName": "Mohamed Salah"
      },
      "position": "FW",
      "stats": {
        "goals": 2,
        "assists": 1,
        "shots": 5,
        "shotsOnTarget": 3,
        "passes": 45,
        "passesAccurate": 38,
        "tackles": 2,
        "rating": 8.5
      }
    }
  ],
  "awayTeam": [...]
}

​
Lineup

​
content.lineup.homeTeam
object
Home team lineup
{
  "starters": [
    {
      "id": 118748,
      "name": "Mohamed Salah",
      "shirtNumber": 11,
      "position": "FW",
      "rating": 8.5
    }
  ],
  "bench": [...],
  "formation": "4-3-3"
}

​
Team Odds Structure

​
Odds Document

​
id
integer
required
Fixture ID
​
name
string
required
Match name
​
date
string
required
Match date/time (ISO 8601)
​
sport
string
required
Sport name
​
league
string
required
League name
​
home
string
required
Home team name
​
away
string
required
Away team name
​
bookmakers
object
required
Bookmaker odds
{
  "Bet365": [
    {
      "name": "Totals",
      "odds": [
        {
          "hdp": 2.5,
          "over": 2.10,
          "under": 1.85,
          "updatedAt": "2024-03-10T14:25:00Z"
        }
      ]
    }
  ],
  "Pinnacle": [...]
}
​
updatedAt
string
Last update timestamp

​
Fixture Statistics

​
Statistics Object

​
type_id
integer
required
Statistic type ID
​
participant_id
integer
Team/player ID
​
location
string
“home” or “away”
​
data.value
integer
required
Statistic value
​
data.type
string
Data type (“total”, “average”, etc.)

​
Type ID Mapping

const TYPE_IDS = {
  GOALS: 52,
  CORNERS: 34,
  YELLOW_CARDS: 84,
  RED_CARDS: 83,
  SHOTS: 42,
  SHOTS_ON_TARGET: 86,
  TACKLES: 78,
  OFFSIDES: 51,
  FOULS: 56,
  SAVES: 57,
  PASSES: 80,
  SUCCESSFUL_PASSES: 81,
  INTERCEPTIONS: 100,
  SUCCESSFUL_DRIBBLES: 109,
  CROSSES: 98
};

​
Example Statistics

[
  {
    "type_id": 52,
    "participant_id": 8650,
    "location": "home",
    "data": {
      "value": 2,
      "type": "total"
    }
  },
  {
    "type_id": 52,
    "participant_id": 8456,
    "location": "away",
    "data": {
      "value": 1,
      "type": "total"
    }
  },
  {
    "type_id": 34,
    "participant_id": 8650,
    "location": "home",
    "data": {
      "value": 6,
      "type": "total"
    }
  }
]

​
Fixture Info Object

​
Common Fields

​
match_id
integer
required
Match ID
​
match_name
string
required
Match name
​
home
string
required
Home team
​
away
string
required
Away team
​
date
string
required
Match date (YYYY-MM-DD)
​
time
string
Match time (HH:MM)
​
league
string
League name
​
sport
string
Sport name
​
participants
array
Array of participant objects
[
  {
    "id": 8650,
    "name": "Liverpool",
    "meta": {
      "location": "home"
    }
  },
  {
    "id": 8456,
    "name": "Manchester City",
    "meta": {
      "location": "away"
    }
  }
]

​
Fixture Status

​
Status Values

  • NS - Not Started
  • LIVE - In Progress
  • HT - Half Time
  • FT - Full Time
  • AET - After Extra Time
  • PEN - Penalties
  • PST - Postponed
  • CANC - Cancelled
  • ABD - Abandoned
  • SUSP - Suspended

​
Check if Finished

def is_fixture_finished(fixture_data: dict) -> bool:
    """Check if fixture has finished"""
    status = fixture_data.get('header', {}).get('status', {})
    return status.get('finished', False)

​
Check if Started

def is_fixture_started(fixture_data: dict) -> bool:
    """Check if fixture has started"""
    status = fixture_data.get('header', {}).get('status', {})
    return status.get('started', False)

​
Example Fixtures

​
Complete Fixture

{
  "general": {
    "matchId": 4193204,
    "matchName": "Liverpool vs Manchester City",
    "matchRound": "Premier League - Round 29",
    "leagueId": 47,
    "leagueName": "Premier League"
  },
  "header": {
    "teams": [
      {
        "id": 8650,
        "name": "Liverpool",
        "score": 2
      },
      {
        "id": 8456,
        "name": "Manchester City",
        "score": 1
      }
    ],
    "status": {
      "started": true,
      "finished": true,
      "cancelled": false,
      "scoreStr": "2-1",
      "reason": {
        "short": "FT",
        "long": "Full-Time"
      },
      "startDateStr": "Mar 10, 16:30"
    }
  },
  "content": {
    "stats": {
      "Periods": {
        "All": {
          "stats": [
            {
              "title": "Possession (%)",
              "stats": ["48", "52"],
              "highlighted": "away"
            },
            {
              "title": "Shots",
              "stats": ["15", "18"],
              "highlighted": "away"
            },
            {
              "title": "Shots on target",
              "stats": ["6", "8"],
              "highlighted": "away"
            },
            {
              "title": "Corners",
              "stats": ["6", "9"],
              "highlighted": "away"
            }
          ]
        }
      }
    },
    "playerStats": {
      "homeTeam": [
        {
          "playerId": 118748,
          "name": {
            "fullName": "Mohamed Salah"
          },
          "stats": {
            "goals": 2,
            "shots": 5,
            "shotsOnTarget": 3
          }
        }
      ]
    }
  }
}

​
Indexes

​
Team Odds Collection

// Match lookup
db.team_odds.createIndex({ "id": 1 }, { unique: true })

// Date range queries
db.team_odds.createIndex({ "date": 1 })

// League filtering
db.team_odds.createIndex({ "league": 1 })

// Sport filtering
db.team_odds.createIndex({ "sport": 1 })

// Update timestamp
db.team_odds.createIndex({ "updatedAt": 1 })

​
References

Build docs developers (and LLMs) love

Get started for freeTalk to us