cfbd_json_py.drives

  1# Creation Date: 08/30/2023 01:13 EDT
  2# Last Updated Date: 08/28/2024 11:00 PM EDT
  3# Author: Joseph Armstrong (armstrongjoseph08@gmail.com)
  4# File Name: drives.py
  5# Purpose: Houses functions pertaining to CFB drive data within the CFBD API.
  6###############################################################################
  7
  8import logging
  9from datetime import datetime
 10
 11import pandas as pd
 12import requests
 13
 14from cfbd_json_py.utls import get_cfbd_api_token
 15
 16
 17def get_cfbd_drives_info(
 18    api_key: str = None,
 19    api_key_dir: str = None,
 20    season: int = None,
 21    season_type: str = "regular",
 22    week: int = None,
 23    team: str = None,
 24    offensive_team: str = None,
 25    defensive_team: str = None,
 26    conference: str = None,
 27    offensive_conference: str = None,
 28    defensive_conference: str = None,
 29    ncaa_division: str = "fbs",
 30    year: int = None,
 31    offense: str = None,
 32    defense: str = None,
 33    classification: str = None,
 34    return_as_dict: bool = False,
 35):
 36    """
 37    Retrieves a list of CFB drives from the CFBD API.
 38
 39    Parameters
 40    ----------
 41    `season` (int, mandatory):
 42        Required argument.
 43        Specifies the season you want CFB drive information from.
 44        This must be specified, otherwise this package, and by extension
 45        the CFBD API, will not accept the request to get CFB drive information.
 46
 47    `api_key` (str, optional):
 48        Semi-optional argument.
 49        If `api_key` is null, this function will attempt to load a CFBD API key
 50        from the python environment, or from a file on this computer.
 51        If `api_key` is not null,
 52        this function will automatically assume that the
 53        inputted `api_key` is a valid CFBD API key.
 54
 55    `api_key_dir` (str, optional):
 56        Optional argument.
 57        If `api_key` is set to am empty string, this variable is ignored.
 58        If `api_key_dir` is null, and `api_key` is null,
 59        this function will try to find
 60        a CFBD API key file in this user's home directory.
 61        If `api_key_dir` is set to a string, and `api_key` is null,
 62        this function will assume that `api_key_dir` is a directory,
 63        and will try to find a CFBD API key file in that directory.
 64
 65    `season_type` (str, semi-optional):
 66        Semi-optional argument.
 67        By default, this will be set to "regular", for the CFB regular season.
 68        If you want CFB drive data for non-regular season games,
 69        set `season_type` to "postseason".
 70        If `season_type` is set to anything but "regular" or "postseason",
 71        a `ValueError()` will be raised.
 72
 73    `week` (int, optional):
 74        Optional argument.
 75        If `week` is set to an integer, this function will attempt
 76        to load CFB drive data from games in that season, and that week.
 77
 78    `team` (str, optional):
 79        Optional argument.
 80        If you only want CFB drive data for a team,
 81        regardless if they are the home/away team,
 82        set `team` to the name of the team you want CFB drive data from.
 83
 84    `offensive_team` (str, optional):
 85        Optional argument.
 86        If you only want CFB drive data from a team, while they are on offense,
 87        regardless if they are the home/away team,
 88        set `team` to the name of the team you want CFB drive data from.
 89
 90    `defensive_team` (str, optional):
 91        Optional argument.
 92        If you only want CFB drive data from a team, while they are on defense,
 93        regardless if they are the home/away team,
 94        set `team` to the name of the team you want CFB drive data from.
 95
 96    `conference` (str, optional):
 97        Optional argument.
 98        If you only want CFB drive data from games
 99        involving teams from a specific conference,
100        set `conference` to the abbreviation
101        of the conference you want CFB drive data from.
102        For a list of conferences,
103        use the `cfbd_json_py.conferences.get_cfbd_conference_info()`
104        function.
105
106    `offensive_conference` (str, optional):
107        Optional argument.
108        If you only want CFB drive data from games
109        where the offensive team is from a specific conference,
110        set `conference` to the abbreviation
111        of the conference you want CFB drive data from.
112        For a list of conferences,
113        use the `cfbd_json_py.conferences.get_cfbd_conference_info()`
114        function.
115
116    `defensive_conference` (str, optional):
117        Optional argument.
118        If you only want CFB drive data from games
119        where the defensive team is from a specific conference,
120        set `conference` to the abbreviation
121        of the conference you want CFB drive data from.
122        For a list of conferences,
123        use the `cfbd_json_py.conferences.get_cfbd_conference_info()`
124        function.
125
126    `ncaa_division` (str, semi-optional):
127        Semi-optional argument.
128        By default, `ncaa_division` will be set to "fbs",
129        short for the Football Bowl Subdivision (FBS),
130        formerly known as D1-A (read as "division one single A"),
131        the highest level in the NCAA football pyramid,
132        where teams can scholarship up to 85 players
133        on their football team solely for athletic ability,
134        and often have the largest athletics budgets
135        within the NCAA.
136
137        Other valid inputs are:
138        - "fcs": Football Championship Subdivision (FCS),
139            formerly known as D1-AA (read as "division one double A").
140            An FCS school is still in the 1st division of the NCAA,
141            making them eligible for the March Madness tournament,
142            but may not have the resources to compete at the FBS level
143            at this time. FCS schools are limited to 63 athletic scholarships
144            for football.
145        - "ii": NCAA Division II. Schools in this and D3 are not
146            eligible for the March Madness tournament,
147            and are limited to 36 athletic scholarships
148            for their football team.
149        - "iii": NCAA Division III. The largest single division within the
150            NCAA football pyramid.
151            D3 schools have the distinction of being part of
152            the only NCAA division that cannot give out scholarships solely
153            for athletic ability.
154
155    `offense` (str):
156        Alternative keyword for `offensive_team`
157
158    `defense` (str):
159        Alternative keyword for `defensive_team`
160
161    `classification` (str):
162        Alternative keyword for `ncaa_division`
163
164    `return_as_dict` (bool, semi-optional):
165        Semi-optional argument.
166        If you want this function to return the data
167        as a dictionary (read: JSON object),
168        instead of a pandas `DataFrame` object,
169        set `return_as_dict` to `True`.
170
171    Usage
172    ----------
173    ```
174    import time
175
176    from cfbd_json_py.drives import get_cfbd_drives_info
177
178    cfbd_key = "tigersAreAwesome"  # placeholder for your CFBD API Key.
179
180    if cfbd_key is not "tigersAreAwesome":
181        print(
182            "Using the user's API key declared in this script " +
183            "for this example."
184        )
185
186        # Get CFB Drive data from the 2020 CFB season.
187        print("Get CFB Drive data from the 2020 CFB season.")
188        json_data = get_cfbd_drives_info(
189            api_key=cfbd_key,
190            season=2020
191        )
192        print(json_data)
193        time.sleep(5)
194
195        # Get CFB Drive data from week 10 of the 2020 CFB season.
196        print("Get CFB Drive data from week 10 of the 2020 CFB season.")
197        json_data = get_cfbd_drives_info(
198            api_key=cfbd_key,
199            season=2020,
200            week=10
201        )
202        print(json_data)
203        time.sleep(5)
204
205        # Get CFB Drive data from games involving the 2020 Cincinnati Bearcats
206        # Football Team.
207        print(
208            "Get CFB Drive data from games involving " +
209            "the 2020 Cincinnati Bearcats Football Team."
210        )
211        json_data = get_cfbd_drives_info(
212            api_key=cfbd_key,
213            season=2020,
214            team="Cincinnati"
215        )
216        print(json_data)
217        time.sleep(5)
218
219        # Get CFB Drive data from games involving the 2020 Ohio Bobcats
220        # Football Team, when Ohio was on offense.
221        print(
222            "Get CFB Drive data from games involving " +
223            "the 2020 Ohio Bobcats Football Team, when Ohio was on offense."
224        )
225        json_data = get_cfbd_drives_info(
226            api_key=cfbd_key,
227            season=2020,
228            offensive_team="Ohio"
229        )
230        print(json_data)
231        time.sleep(5)
232
233        # Get CFB Drive data from games involving the 2020 Ohio State Buckeyes
234        # Football Team, when Ohio was on offense.
235        print(
236            "Get CFB Drive data from games involving " +
237            "the 2020 Ohio State Buckeyes Football Team, " +
238            "when Ohio State was on defense."
239        )
240        json_data = get_cfbd_drives_info(
241            api_key=cfbd_key,
242            season=2020,
243            defensive_team="Ohio State"
244        )
245        print(json_data)
246        time.sleep(5)
247
248        # Get CFB Drive data from Big 12 games in the 2020 CFB season.
249        print(
250            "Get CFB Drive data from games involving " +
251            "the 2020 Ohio State Buckeyes Football Team, " +
252            "when Ohio State was on defense."
253        )
254        json_data = get_cfbd_drives_info(
255            api_key=cfbd_key,
256            season=2020,
257            conference="B12"
258        )
259        print(json_data)
260        time.sleep(5)
261
262        # Get CFB Drive data from Big 10 (B1G) games in the 2020 CFB season,
263        # where the Big 10 team was on offense.
264        print(
265            "Get CFB Drive data from games involving " +
266            "the 2020 Ohio State Buckeyes Football Team, " +
267            "when Ohio State was on defense."
268        )
269        json_data = get_cfbd_drives_info(
270            api_key=cfbd_key,
271            season=2020,
272            offensive_conference="B1G"
273        )
274        print(json_data)
275        time.sleep(5)
276
277        # Get CFB Drive data from  Mid-American Conference (MAC) games
278        # in the 2020 CFB season, where the MAC team was on offense.
279        print(
280            "Get CFB Drive data from games involving " +
281            "the 2020 Ohio State Buckeyes Football Team, " +
282            "when Ohio State was on defense."
283        )
284        json_data = get_cfbd_drives_info(
285            api_key=cfbd_key,
286            season=2020,
287            defensive_conference="MAC"
288        )
289        print(json_data)
290        time.sleep(5)
291
292        # Get CFB Drive data from Football Championship Subdivision (FCS) games
293        # in week 3 of the 2020 CFB season,
294        # where the MAC team was on offense.
295        print(
296            "Get CFB Drive data from games involving " +
297            "the 2020 Ohio State Buckeyes Football Team, " +
298            "when Ohio State was on defense."
299        )
300        json_data = get_cfbd_drives_info(
301            api_key=cfbd_key,
302            season=2020,
303            week=3,
304            ncaa_division="fcs"
305        )
306        print(json_data)
307        time.sleep(5)
308
309        # You can also tell this function to just return the API call as
310        # a Dictionary (read: JSON) object.
311        print(
312            "You can also tell this function to just return the API call " +
313            "as a Dictionary (read: JSON) object."
314        )
315        json_data = get_cfbd_drives_info(
316            season=2020,
317            week=10,
318            api_key=cfbd_key,
319            return_as_dict=True
320        )
321        print(json_data)
322
323    else:
324        # Alternatively, if the CFBD API key exists in this python environment,
325        # or it's been set by cfbd_json_py.utls.set_cfbd_api_token(),
326        # you could just call these functions directly,
327        # without setting the API key in the script.
328        print(
329            "Using the user's API key supposedly loaded " +
330            "into this python environment for this example."
331        )
332
333        # Get CFB Drive data from the 2020 CFB season.
334        print("Get CFB Drive data from the 2020 CFB season.")
335        json_data = get_cfbd_drives_info(
336            season=2020
337        )
338        print(json_data)
339        time.sleep(5)
340
341        # Get CFB Drive data from week 10 of the 2020 CFB season.
342        print("Get CFB Drive data from week 10 of the 2020 CFB season.")
343        json_data = get_cfbd_drives_info(
344            season=2020,
345            week=10
346        )
347        print(json_data)
348        time.sleep(5)
349
350        # Get CFB Drive data from games involving the 2020 Cincinnati Bearcats
351        # Football Team.
352        print(
353            "Get CFB Drive data from games involving " +
354            "the 2020 Cincinnati Bearcats Football Team."
355        )
356        json_data = get_cfbd_drives_info(
357            season=2020,
358            team="Cincinnati"
359        )
360        print(json_data)
361        time.sleep(5)
362
363        # Get CFB Drive data from games involving the 2020 Ohio Bobcats
364        # Football Team, when Ohio was on offense.
365        print(
366            "Get CFB Drive data from games involving " +
367            "the 2020 Ohio Bobcats Football Team, when Ohio was on offense."
368        )
369        json_data = get_cfbd_drives_info(
370            season=2020,
371            offensive_team="Ohio"
372        )
373        print(json_data)
374        time.sleep(5)
375
376        # Get CFB Drive data from games involving the 2020 Ohio State Buckeyes
377        # Football Team, when Ohio was on offense.
378        print(
379            "Get CFB Drive data from games involving " +
380            "the 2020 Ohio State Buckeyes Football Team, " +
381            "when Ohio State was on defense."
382        )
383        json_data = get_cfbd_drives_info(
384            season=2020,
385            defensive_team="Ohio State"
386        )
387        print(json_data)
388        time.sleep(5)
389
390        # Get CFB Drive data from Big 12 games in the 2020 CFB season.
391        print(
392            "Get CFB Drive data from games involving " +
393            "the 2020 Ohio State Buckeyes Football Team, " +
394            "when Ohio State was on defense."
395        )
396        json_data = get_cfbd_drives_info(
397            season=2020,
398            conference="B12"
399        )
400        print(json_data)
401        time.sleep(5)
402
403        # Get CFB Drive data from Big 10 (B1G) games in the 2020 CFB season,
404        # where the Big 10 team was on offense.
405        print(
406            "Get CFB Drive data from games involving " +
407            "the 2020 Ohio State Buckeyes Football Team, " +
408            "when Ohio State was on defense."
409        )
410        json_data = get_cfbd_drives_info(
411            season=2020,
412            offensive_conference="B1G"
413        )
414        print(json_data)
415        time.sleep(5)
416
417        # Get CFB Drive data from  Mid-American Conference (MAC) games
418        # in the 2020 CFB season, where the MAC team was on offense.
419        print(
420            "Get CFB Drive data from games involving " +
421            "the 2020 Ohio State Buckeyes Football Team, " +
422            "when Ohio State was on defense."
423        )
424        json_data = get_cfbd_drives_info(
425            season=2020,
426            defensive_conference="MAC"
427        )
428        print(json_data)
429        time.sleep(5)
430
431        # Get CFB Drive data from Football Championship Subdivision (FCS) games
432        # in week 3 of the 2020 CFB season,
433        # where the MAC team was on offense.
434        print(
435            "Get CFB Drive data from games involving " +
436            "the 2020 Ohio State Buckeyes Football Team, " +
437            "when Ohio State was on defense."
438        )
439        json_data = get_cfbd_drives_info(
440            season=2020,
441            week=3,
442            ncaa_division="fcs"
443        )
444        print(json_data)
445        time.sleep(5)
446
447        # You can also tell this function to just return the API call as
448        # a Dictionary (read: JSON) object.
449        print(
450            "You can also tell this function to just return the API call " +
451            "as a Dictionary (read: JSON) object."
452        )
453        json_data = get_cfbd_drives_info(
454            season=2020,
455            week=10,
456            return_as_dict=True
457        )
458        print(json_data)
459
460    ```
461
462    Returns
463    ----------
464    A pandas `DataFrame` object with CFB drive data,
465    or (if `return_as_dict` is set to `True`)
466    a dictionary object with CFB drive data.
467
468    """
469    now = datetime.now()
470    cfb_drives_df = pd.DataFrame()
471    # row_df = pd.DataFrame()
472    url = "https://api.collegefootballdata.com/drives"
473
474    # Input validation
475    ##########################################################################
476
477    # `year` to `season`
478    if season is not None and year is not None and (year is not season):
479        raise ValueError(
480            "When using this function, "
481            + "please specify a season in EITHER `year` or `season`."
482        )
483    if season is not None:
484        pass
485    elif year is not None:
486        season = year
487    else:
488        raise ValueError("No year/season inputted for this function.")
489
490    # `offense` to `offensive_team`
491    if (
492        offense is not None
493        and offensive_team is not None
494        and (offense is not offensive_team)
495    ):
496        raise ValueError(
497            "When using this function, "
498            + "please specify a season in EITHER "
499            + "`offense` or `offensive_team`."
500        )
501    if offensive_team is not None:
502        pass
503    elif offense is not None:
504        offensive_team = offense
505
506    # `defense` to `defensive_team`
507    if (
508        defense is not None
509        and defensive_team is not None
510        and (defense is not defensive_team)
511    ):
512        raise ValueError(
513            "When using this function, "
514            + "please specify a season in EITHER "
515            + "`defense` or `defensive_team`."
516        )
517    if defensive_team is not None:
518        pass
519    elif defense is not None:
520        defensive_team = defense
521
522    # `classification` to `ncaa_division`
523    if (
524        classification is not None
525        and ncaa_division is not None
526        and (classification is not ncaa_division)
527    ):
528        raise ValueError(
529            "When using this function, "
530            + "please specify a season in EITHER "
531            + "`classification` or `ncaa_division`."
532        )
533    if ncaa_division is not None:
534        pass
535    elif defense is not None:
536        ncaa_division = classification
537
538    if api_key is not None:
539        real_api_key = api_key
540        del api_key
541    else:
542        real_api_key = get_cfbd_api_token(api_key_dir=api_key_dir)
543
544    if real_api_key == "tigersAreAwesome":
545        raise ValueError(
546            "You actually need to change `cfbd_key` to your CFBD API key."
547        )
548    elif "Bearer " in real_api_key:
549        pass
550    elif "Bearer" in real_api_key:
551        real_api_key = real_api_key.replace("Bearer", "Bearer ")
552    else:
553        real_api_key = "Bearer " + real_api_key
554
555    if season is None:
556        # This should never happen without user tampering, but if it does,
557        # we need to raise an error,
558        # because the CFBD API will refuse this call without a valid season.
559        raise SystemError(
560            "I don't know how, I don't know why, "
561            + "but you managed to call this function "
562            + "while `season` was `None` (NULL),"
563            + " and the function got to this point in the code."
564            + "\nIf you have a GitHub account, "
565            + "please raise an issue on this python package's GitHub page:\n"
566            + "https://github.com/armstjc/cfbd-json-py/issues"
567        )
568    elif season > (now.year + 1):
569        raise ValueError(f"`season` cannot be greater than {season}.")
570    elif season < 1869:
571        raise ValueError("`season` cannot be less than 1869.")
572
573    if season_type != "regular" and season_type != "postseason":
574        raise ValueError(
575            '`season_type` must be set to either ' +
576            '"regular" or "postseason" for this function to work.'
577        )
578
579    if (
580        ncaa_division.lower() == "fbs"
581        or ncaa_division.lower() == "fcs"
582        or ncaa_division.lower() == "ii"
583        or ncaa_division.lower() == "iii"
584    ):
585        pass
586    else:
587        raise ValueError(
588            "An invalid NCAA Division was inputted when calling this function."
589            + '\nValid inputs are:\n-"fbs"\n-"fcs"\n-"ii"\n-"iii"'
590            + f"\n\nYou entered:\n{ncaa_division}"
591        )
592
593    # URL builder
594    ##########################################################################
595
596    # Required by API
597    url += f"?seasonType={season_type}"
598
599    url += f"&year={season}"
600
601    if week is not None:
602        url += f"&week={week}"
603
604    if team is not None:
605        url += f"&team={team}"
606
607    if offensive_team is not None:
608        url += f"&offense={offensive_team}"
609
610    if defensive_team is not None:
611        url += f"&defense={defensive_team}"
612
613    if conference is not None:
614        url += f"&conference={conference}"
615
616    if offensive_conference is not None:
617        url += f"&offenseConference={offensive_conference}"
618
619    if defensive_conference is not None:
620        url += f"&defenseConference={defensive_conference}"
621
622    if ncaa_division is not None:
623        url += f"&classification={ncaa_division.lower()}"
624
625    headers = {
626        "Authorization": f"{real_api_key}",
627        "accept": "application/json"
628    }
629
630    response = requests.get(url, headers=headers)
631
632    if response.status_code == 200:
633        pass
634    elif response.status_code == 401:
635        raise ConnectionRefusedError(
636            "Could not connect. The connection was refused." +
637            "\nHTTP Status Code 401."
638        )
639    else:
640        raise ConnectionError(
641            f"Could not connect.\nHTTP Status code {response.status_code}"
642        )
643
644    json_data = response.json()
645
646    if return_as_dict is True:
647        return json_data
648
649    cfb_drives_df = pd.json_normalize(json_data)
650    cfb_drives_df.to_csv("test.csv")
651    # print(cfb_drives_df.columns)
652    cfb_drives_df.rename(
653        columns={
654            "offense": "offense_team_name",
655            "offense_conference": "offense_conference_name",
656            "defense": "defense_name",
657            "defense_conference": "defense_conference_name",
658            "id": "drive_id",
659            "scoring": "is_scoring_drive",
660            "start_time.minutes": "start_time_minutes",
661            "start_time.seconds": "start_time_seconds",
662            "end_time.minutes": "end_time_minutes",
663            "end_time.seconds": "end_time_seconds",
664            "elapsed.minutes": "elapsed_minutes",
665            "elapsed.seconds": "elapsed_seconds",
666        },
667        inplace=True,
668    )
669    if len(cfb_drives_df) == 0:
670        logging.error(
671            "The CFBD API accepted your inputs, "
672            + "but found no data within your specified input parameters."
673            + " Please double check your input parameters."
674        )
675
676    return cfb_drives_df