Skip to content

Event

Event Class

Represents a sports event within the ESPN API framework.

This class acts as a central unit for encapsulating all relevant data associated with a sporting event, including participating teams, venue details, drives (football), play-by-play actions (basketball), competition metadata, and betting odds.

Attributes:

Name Type Description
event_json dict

The raw JSON data from ESPN describing the event.
espn_instance PYESPN

The active ESPN API interface used for data lookups.
url_ref str

ESPN API reference URL to this event.
event_id int

Unique identifier for the event.
date str

Date and time of the event in ISO format.
event_name str

Full name of the event.
short_name str

Abbreviated name of the event.
competition_type str

Type of competition (e.g. "regular", "postseason").
venue_json dict

Raw JSON data representing the venue.
event_venue Venue

Venue object built from the venue JSON.
event_notes list

Optional notes or metadata about the event.
home_team Team

Team object representing the home team.
away_team Team

Team object representing the away team.
api_info dict

League-specific metadata used to construct ESPN URLs.
competition Competition

An object containing metadata about the specific competition.
odds list[GameOdds]

List of betting odds (if available).
drives list[Drive] or None

A list of Drive instances for football games.
plays list[Play] or None

A list of Play instances for basketball games.

Methods:

Name Description
load_betting_odds

Fetches and parses multi-page betting odds data.
load_play_by_play

Routes to appropriate play-by-play loader depending on sport type.
_load_competition_data

Loads metadata about the specific competition instance.
_load_teams

Populates home_team and away_team attributes from competitors JSON.
_load_basketball_plays

Loads all basketball plays as Play objects.
_load_drive_data

Loads all football drives as Drive objects.
to_dict

Returns the original raw JSON for this event.
__repr__

A readable string representation showing the event short name and date.
Source code in pyespn/classes/event.py 
  8
  9
 10
 11
 12
 13
 14
 15
 16
 17
 18
 19
 20
 21
 22
 23
 24
 25
 26
 27
 28
 29
 30
 31
 32
 33
 34
 35
 36
 37
 38
 39
 40
 41
 42
 43
 44
 45
 46
 47
 48
 49
 50
 51
 52
 53
 54
 55
 56
 57
 58
 59
 60
 61
 62
 63
 64
 65
 66
 67
 68
 69
 70
 71
 72
 73
 74
 75
 76
 77
 78
 79
 80
 81
 82
 83
 84
 85
 86
 87
 88
 89
 90
 91
 92
 93
 94
 95
 96
 97
 98
 99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
302
303
304
305
306
307
308
309
310
311
312
313
314
315
316
317
318
319
@validate_json("event_json")
class Event:
    """
    Represents a sports event within the ESPN API framework.

    This class acts as a central unit for encapsulating all relevant data associated with
    a sporting event, including participating teams, venue details, drives (football),
    play-by-play actions (basketball), competition metadata, and betting odds.

    Attributes:
        event_json (dict): The raw JSON data from ESPN describing the event.
        espn_instance (PYESPN): The active ESPN API interface used for data lookups.
        url_ref (str): ESPN API reference URL to this event.
        event_id (int): Unique identifier for the event.
        date (str): Date and time of the event in ISO format.
        event_name (str): Full name of the event.
        short_name (str): Abbreviated name of the event.
        competition_type (str): Type of competition (e.g. "regular", "postseason").
        venue_json (dict): Raw JSON data representing the venue.
        event_venue (Venue): Venue object built from the venue JSON.
        event_notes (list): Optional notes or metadata about the event.
        home_team (Team): Team object representing the home team.
        away_team (Team): Team object representing the away team.
        api_info (dict): League-specific metadata used to construct ESPN URLs.
        competition (Competition): An object containing metadata about the specific competition.
        odds (list[GameOdds]): List of betting odds (if available).
        drives (list[Drive] or None): A list of `Drive` instances for football games.
        plays (list[Play] or None): A list of `Play` instances for basketball games.

    Methods:
        load_betting_odds():
            Fetches and parses multi-page betting odds data.

        load_play_by_play():
            Routes to appropriate play-by-play loader depending on sport type.

        _load_competition_data():
            Loads metadata about the specific competition instance.

        _load_teams():
            Populates home_team and away_team attributes from competitors JSON.

        _load_basketball_plays():
            Loads all basketball plays as `Play` objects.

        _load_drive_data():
            Loads all football drives as `Drive` objects.

        to_dict() -> dict:
            Returns the original raw JSON for this event.

        __repr__() -> str:
            A readable string representation showing the event short name and date.
    """

    def __init__(self, event_json: dict, espn_instance,
                 load_game_odds: bool = False,
                 load_play_by_play: bool = False):
        """
        Initializes an Event instance with the provided JSON data.

        This constructor optionally loads betting odds and play-by-play data based on
        the supplied flags. By default, those are not loaded unless explicitly enabled.

        Args:
            event_json (dict): The JSON data containing event details.
            espn_instance (PYESPN): The parent `PYESPN` instance for API interaction.
            load_game_odds (bool, optional): If True, fetch and load the betting odds
                                             for the event. Defaults to False.
            load_play_by_play (bool, optional): If True, fetch and load the play-by-play
                                                data (either drives or plays depending
                                                on sport). Defaults to False.
        """
        from pyespn.classes.venue import Venue
        self.competition = None
        self.event_json = event_json
        self._espn_instance = espn_instance
        self.url_ref = self.event_json.get('$ref')
        self._event_id = self.event_json.get('id')
        self.date = self.event_json.get('date')
        self.event_name = self.event_json.get('name')
        self.short_name = self.event_json.get('shortName')
        self.competition_type = self.event_json.get('competitions', [])[0].get('type', {}).get('type')
        self.venue_json = self.event_json.get('competitions', [])[0].get('venue', {})
        self.event_venue = Venue(venue_json=self.venue_json,
                                 espn_instance=self._espn_instance)
        self.event_notes = self.event_json.get('competitions', [])[0].get('notes', [])
        self._home_team = None
        self._away_team = None
        self._odds = None
        self._drives = None
        self._plays = None
        self.api_info = self._espn_instance.api_mapping
        self._load_teams()
        self._load_competition_data()
        if load_game_odds:
            self.load_betting_odds()
        if load_play_by_play:
            self.load_play_by_play()

    @property
    def event_id(self):
        """
            str: the id for the event
        """
        return self._event_id

    @property
    def espn_instance(self):
        """
            PYESPN: the espn client instance associated with the class
        """
        return self._espn_instance

    @property
    def drives(self):
        """
            list[Drive]: a list of drives for the given event
        """
        return self._drives

    @property
    def plays(self):
        """
            list[Play]: a list of drives for the given event
        """
        return self._plays

    @property
    def odds(self):
        """
            list[Betting]: a list of Odds for the given game
        """
        return self._odds

    @property
    def away_team(self):
        """
            Team: the away team as a Team object
        """
        return self._away_team

    @property
    def home_team(self):
        """
            Team: the home team as a Team object
        """
        return self._home_team

    def _load_teams(self):
        """
        Private method to fetch and assign the competing teams for the event.

        This method retrieves the teams' JSON data using their API references and
        initializes `Team` instances for `team1` and `team2`.
        """
        team1 = self.event_json.get('competitions', [])[0].get('competitors')[0]
        team2 = self.event_json.get('competitions', [])[0].get('competitors')[1]
        team1_id = team1.get('id')
        team2_id = team2.get('id')

        if team1.get('homeAway') == 'home':
            self._home_team = self._espn_instance.get_team_by_id(team1_id)

            self._away_team = self._espn_instance.get_team_by_id(team2_id)
        else:
            self._home_team = self._espn_instance.get_team_by_id(team2_id)

            self._away_team = self._espn_instance.get_team_by_id(team1_id)

    def __repr__(self) -> str:
        """
        Returns a string representation of the Team instance.

        Returns:
            str: A formatted string with the events data.
        """
        return f"<Event | {self.short_name} {self.date}>"

    def load_betting_odds(self):
        """
        method to fetch and assign betting odds for the event.

        This method constructs the appropriate URL using event and league data, then retrieves
        and parses odds data from each available page. The results are stored in the `self.odds` list
        as `GameOdds` instances.
        """

        url = f'http://sports.core.api.espn.com/{self._espn_instance.v}/sports/{self.api_info["sport"]}/leagues/{self.api_info["league"]}/events/{self._event_id}/competitions/{self._event_id}/odds'
        page_content = fetch_espn_data(url)
        pages = page_content.get('pageCount', 0)

        def fetch_and_parse_odds(page):
            page_url = url + f'?page={page}'
            odds_content = fetch_espn_data(page_url)
            return [
                GameOdds(odds_json=odd,
                         espn_instance=self._espn_instance,
                         event_instance=self)
                for odd in odds_content.get('items', [])
            ]

        event_odds = []
        with ThreadPoolExecutor() as executor:
            futures = [executor.submit(fetch_and_parse_odds, page) for page in range(1, pages + 1)]
            for future in as_completed(futures):
                try:
                    event_odds.extend(future.result())
                except Exception as e:
                    print(f"Error fetching betting odds page: {e}")

        self._odds = event_odds

    def _load_competition_data(self):
        """
        Private method to fetch and assign competition details for the event.

        This method retrieves the competition data for the event and initializes a `Competition`
        object using the JSON data, storing it in the `self.competition` attribute.
        """
        url = f'http://sports.core.api.espn.com/{self._espn_instance.v}/sports/{self.api_info["sport"]}/leagues/{self.api_info["league"]}/events/{self._event_id}/competitions/{self._event_id}'
        competition_content = fetch_espn_data(url)

        self.competition = Competition(competition_json=competition_content,
                                       espn_instance=self._espn_instance,
                                       event_instance=self)

    def load_play_by_play(self):
        """
        Private method to load play-by-play data for the event.

        This method routes the data fetching logic based on the sport type—calling
        `_load_basketball_plays()` for basketball and `_load_drive_data()` for football.
        """
        if self.api_info['sport'] == 'basketball':
            self._load_basketball_plays()
        elif self.api_info['sport'] == 'football':
            self._load_drive_data()

    def _load_basketball_plays(self):
        """
        Private method to fetch and assign play-by-play data for a basketball game.

        Uses multi-threaded requests to efficiently load all play pages and converts each play
        item into a `Play` object. The complete list is assigned to `self.plays`.
        """
        url = f'http://sports.core.api.espn.com/{self._espn_instance.v}/sports/{self.api_info["sport"]}/leagues/{self.api_info["league"]}/events/{self._event_id}/competitions/{self._event_id}/plays'
        page_content = fetch_espn_data(url)
        pages = page_content.get('pageCount', 0)

        def fetch_and_parse_plays(page):
            page_url = url + f'?page={page}'
            play_content = fetch_espn_data(page_url)
            return [
                Play(play_json=play,
                     espn_instance=self._espn_instance,
                     event_instance=self,
                     drive_instance=None)
                for play in play_content.get('items', [])
            ]

        plays = []
        with ThreadPoolExecutor() as executor:
            futures = [executor.submit(fetch_and_parse_plays, page) for page in range(1, pages + 1)]
            for future in as_completed(futures):
                try:
                    plays.extend(future.result())
                except Exception as e:
                    print(f"Error fetching plays page: {e}")

        self._plays = plays

    def _load_drive_data(self):
        """
        Private method to fetch and assign drive data for a football game.

        Retrieves all drives associated with the competition and converts each drive item
        into a `Drive` object. The resulting list is stored in `self.drives`.
        """
        url = f'http://sports.core.api.espn.com/{self._espn_instance.v}/sports/{self.api_info["sport"]}/leagues/{self.api_info["league"]}/events/{self._event_id}/competitions/{self._event_id}/drives'
        page_content = fetch_espn_data(url)
        pages = page_content.get('pageCount', 0)

        def fetch_and_parse_drives(page):
            page_url = url + f'?page={page}'
            drive_content = fetch_espn_data(page_url)
            return [
                Drive(drive_json=drive,
                      espn_instance=self._espn_instance,
                      event_instance=self)
                for drive in drive_content.get('items', [])
            ]

        drives = []
        with ThreadPoolExecutor() as executor:
            futures = [executor.submit(fetch_and_parse_drives, page) for page in range(1, pages + 1)]
            for future in as_completed(futures):
                try:
                    drives.extend(future.result())
                except Exception as e:
                    print(f"Error fetching drive data page: {e}")

        self._drives = drives

    def to_dict(self) -> dict:
        """
        Converts the Event instance to its original JSON dictionary.

        Returns:
            dict: The event's raw JSON data.
        """
        return self.event_json

away_team property

Team: the away team as a Team object

drives property

list[Drive]: a list of drives for the given event

espn_instance property

PYESPN: the espn client instance associated with the class

event_id property

str: the id for the event

home_team property

Team: the home team as a Team object

odds property

list[Betting]: a list of Odds for the given game

plays property

list[Play]: a list of drives for the given event

__init__(event_json, espn_instance, load_game_odds=False, load_play_by_play=False)

Initializes an Event instance with the provided JSON data.

This constructor optionally loads betting odds and play-by-play data based on the supplied flags. By default, those are not loaded unless explicitly enabled.

Parameters:

Name Type Description Default
event_json dict

The JSON data containing event details.

 required
espn_instance PYESPN

The parent PYESPN instance for API interaction.

 required
load_game_odds bool

If True, fetch and load the betting odds for the event. Defaults to False.

 False
load_play_by_play bool

If True, fetch and load the play-by-play data (either drives or plays depending on sport). Defaults to False.

 False
Source code in pyespn/classes/event.py 
 63
 64
 65
 66
 67
 68
 69
 70
 71
 72
 73
 74
 75
 76
 77
 78
 79
 80
 81
 82
 83
 84
 85
 86
 87
 88
 89
 90
 91
 92
 93
 94
 95
 96
 97
 98
 99
100
101
102
103
104
105
106
def __init__(self, event_json: dict, espn_instance,
             load_game_odds: bool = False,
             load_play_by_play: bool = False):
    """
    Initializes an Event instance with the provided JSON data.

    This constructor optionally loads betting odds and play-by-play data based on
    the supplied flags. By default, those are not loaded unless explicitly enabled.

    Args:
        event_json (dict): The JSON data containing event details.
        espn_instance (PYESPN): The parent `PYESPN` instance for API interaction.
        load_game_odds (bool, optional): If True, fetch and load the betting odds
                                         for the event. Defaults to False.
        load_play_by_play (bool, optional): If True, fetch and load the play-by-play
                                            data (either drives or plays depending
                                            on sport). Defaults to False.
    """
    from pyespn.classes.venue import Venue
    self.competition = None
    self.event_json = event_json
    self._espn_instance = espn_instance
    self.url_ref = self.event_json.get('$ref')
    self._event_id = self.event_json.get('id')
    self.date = self.event_json.get('date')
    self.event_name = self.event_json.get('name')
    self.short_name = self.event_json.get('shortName')
    self.competition_type = self.event_json.get('competitions', [])[0].get('type', {}).get('type')
    self.venue_json = self.event_json.get('competitions', [])[0].get('venue', {})
    self.event_venue = Venue(venue_json=self.venue_json,
                             espn_instance=self._espn_instance)
    self.event_notes = self.event_json.get('competitions', [])[0].get('notes', [])
    self._home_team = None
    self._away_team = None
    self._odds = None
    self._drives = None
    self._plays = None
    self.api_info = self._espn_instance.api_mapping
    self._load_teams()
    self._load_competition_data()
    if load_game_odds:
        self.load_betting_odds()
    if load_play_by_play:
        self.load_play_by_play()

__repr__()

Returns a string representation of the Team instance.

Returns:

Name Type Description
str str

A formatted string with the events data.
Source code in pyespn/classes/event.py 
178
179
180
181
182
183
184
185
def __repr__(self) -> str:
    """
    Returns a string representation of the Team instance.

    Returns:
        str: A formatted string with the events data.
    """
    return f"<Event | {self.short_name} {self.date}>"

load_betting_odds()

method to fetch and assign betting odds for the event.

This method constructs the appropriate URL using event and league data, then retrieves and parses odds data from each available page. The results are stored in the self.odds list as GameOdds instances.

Source code in pyespn/classes/event.py 
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
def load_betting_odds(self):
    """
    method to fetch and assign betting odds for the event.

    This method constructs the appropriate URL using event and league data, then retrieves
    and parses odds data from each available page. The results are stored in the `self.odds` list
    as `GameOdds` instances.
    """

    url = f'http://sports.core.api.espn.com/{self._espn_instance.v}/sports/{self.api_info["sport"]}/leagues/{self.api_info["league"]}/events/{self._event_id}/competitions/{self._event_id}/odds'
    page_content = fetch_espn_data(url)
    pages = page_content.get('pageCount', 0)

    def fetch_and_parse_odds(page):
        page_url = url + f'?page={page}'
        odds_content = fetch_espn_data(page_url)
        return [
            GameOdds(odds_json=odd,
                     espn_instance=self._espn_instance,
                     event_instance=self)
            for odd in odds_content.get('items', [])
        ]

    event_odds = []
    with ThreadPoolExecutor() as executor:
        futures = [executor.submit(fetch_and_parse_odds, page) for page in range(1, pages + 1)]
        for future in as_completed(futures):
            try:
                event_odds.extend(future.result())
            except Exception as e:
                print(f"Error fetching betting odds page: {e}")

    self._odds = event_odds

load_play_by_play()

Private method to load play-by-play data for the event.

This method routes the data fetching logic based on the sport type—calling _load_basketball_plays() for basketball and _load_drive_data() for football.

Source code in pyespn/classes/event.py 
235
236
237
238
239
240
241
242
243
244
245
def load_play_by_play(self):
    """
    Private method to load play-by-play data for the event.

    This method routes the data fetching logic based on the sport type—calling
    `_load_basketball_plays()` for basketball and `_load_drive_data()` for football.
    """
    if self.api_info['sport'] == 'basketball':
        self._load_basketball_plays()
    elif self.api_info['sport'] == 'football':
        self._load_drive_data()

to_dict()

Converts the Event instance to its original JSON dictionary.

Returns:

Name Type Description
dict dict

The event's raw JSON data.
Source code in pyespn/classes/event.py 
312
313
314
315
316
317
318
319
def to_dict(self) -> dict:
    """
    Converts the Event instance to its original JSON dictionary.

    Returns:
        dict: The event's raw JSON data.
    """
    return self.event_json