cfbd_json_py.teams

   1# Creation Date: 08/30/2023 01:13 EDT
   2# Last Updated Date: 08/13/2024 02:10 PM EDT
   3# Author: Joseph Armstrong (armstrongjoseph08@gmail.com)
   4# File Name: teams.py
   5# Purpose: Houses functions pertaining to CFB team data within the CFBD API.
   6###############################################################################
   7
   8import warnings
   9from datetime import datetime
  10
  11import numpy as np
  12import pandas as pd
  13import requests
  14from tqdm import tqdm
  15
  16from cfbd_json_py.utls import get_cfbd_api_token
  17
  18
  19def get_cfbd_team_information(
  20    api_key: str = None,
  21    api_key_dir: str = None,
  22    conference: str = None,
  23    return_as_dict: bool = False,
  24):
  25    """
  26    Allows you to get CFB team information from the CFBD API.
  27
  28    Parameters
  29    ----------
  30    `api_key` (str, optional):
  31        Semi-optional argument.
  32        If `api_key` is null, this function will attempt to load a CFBD API key
  33        from the python environment, or from a file on this computer.
  34        If `api_key` is not null, this function will automatically
  35        assume that the inputted `api_key` is a valid CFBD API key.
  36
  37    `api_key_dir` (str, optional):
  38        Optional argument.
  39        If `api_key` is set to am empty string, this variable is ignored.
  40        If `api_key_dir` is null, and `api_key` is null,
  41        this function will try to find
  42        a CFBD API key file in this user's home directory.
  43        If `api_key_dir` is set to a string, and `api_key` is null,
  44        this function will assume that `api_key_dir` is a directory,
  45        and will try to find a CFBD API key file in that directory.
  46
  47    `conference` (str, optional):
  48        Optional argument.
  49        If you only want CFB team information from a specific conference,
  50        set `conference` to the abbreviation
  51        of the conference you want CFB team information from.
  52        For a list of conferences,
  53        use the `cfbd_json_py.conferences.get_cfbd_conference_info()`
  54        function.
  55
  56    `return_as_dict` (bool, semi-optional):
  57        Semi-optional argument.
  58        If you want this function to return
  59        the data as a dictionary (read: JSON object),
  60        instead of a pandas `DataFrame` object,
  61        set `return_as_dict` to `True`.
  62
  63    Usage
  64    ----------
  65    ```
  66    import time
  67
  68    from cfbd_json_py.teams import get_cfbd_team_information
  69
  70
  71    cfbd_key = "tigersAreAwesome"  # placeholder for your CFBD API Key.
  72
  73    if cfbd_key != "tigersAreAwesome":
  74        print(
  75            "Using the user's API key declared "+
  76            "in this script for this example."
  77        )
  78
  79        # Get CFB team information for all known CFB teams.
  80        print("Get CFB team information for all known CFB teams.")
  81        json_data = get_cfbd_team_information(
  82            api_key=cfbd_key
  83        )
  84        print(json_data)
  85        time.sleep(5)
  86
  87
  88        # Get CFB team information for all known
  89        # Southeastern conference (SEC) CFB teams.
  90        print(
  91            "Get CFB team information for all known " +
  92            "Southeastern conference (SEC) CFB teams."
  93        )
  94        json_data = get_cfbd_team_information(
  95            api_key=cfbd_key,
  96            conference="SEC"
  97        )
  98        print(json_data)
  99        time.sleep(5)
 100
 101
 102        # You can also tell this function to just return the API call as
 103        # a Dictionary (read: JSON) object.
 104        print(
 105            "You can also tell this function to " +
 106            "just return the API call as a Dictionary (read: JSON) object."
 107        )
 108        json_data = get_cfbd_team_information(
 109            api_key=cfbd_key,
 110            conference="B1G",
 111            return_as_dict=True
 112        )
 113        print(json_data)
 114
 115    else:
 116        # Alternatively, if the CFBD API key exists in this python environment,
 117        # or it's been set by cfbd_json_py.utls.set_cfbd_api_token(),
 118        # you could just call these functions directly,
 119        # without setting the API key in the script.
 120        print(
 121            "Using the user's API key supposedly loaded into " +
 122            "this python environment for this example."
 123        )
 124
 125        # Get CFB team information for all known CFB teams.
 126        print("Get CFB team information for all known CFB teams.")
 127        json_data = get_cfbd_team_information()
 128        print(json_data)
 129        time.sleep(5)
 130
 131
 132        # Get CFB team information for all known
 133        # Southeastern conference (SEC) CFB teams.
 134        print(
 135            "Get CFB team information for all known " +
 136            "Southeastern conference (SEC) CFB teams."
 137        )
 138        json_data = get_cfbd_team_information(
 139            conference="SEC"
 140        )
 141        print(json_data)
 142        time.sleep(5)
 143
 144
 145        # You can also tell this function to just return the API call as
 146        # a Dictionary (read: JSON) object.
 147        print(
 148            "You can also tell this function to just return " +
 149            "the API call as a Dictionary (read: JSON) object."
 150        )
 151        json_data = get_cfbd_team_information(
 152            conference="B1G",
 153            return_as_dict=True
 154        )
 155        print(json_data)
 156
 157    ```
 158    Returns
 159    ----------
 160    A pandas `DataFrame` object with CFB team information,
 161    or (if `return_as_dict` is set to `True`)
 162    a dictionary object with CFB team information.
 163
 164    """
 165    warnings.simplefilter(action="ignore", category=FutureWarning)
 166
 167    teams_df = pd.DataFrame()
 168    row_df = pd.DataFrame()
 169    url = "https://api.collegefootballdata.com/teams"
 170
 171    ##########################################################################
 172
 173    if api_key is not None:
 174        real_api_key = api_key
 175        del api_key
 176    else:
 177        real_api_key = get_cfbd_api_token(api_key_dir=api_key_dir)
 178
 179    if real_api_key == "tigersAreAwesome":
 180        raise ValueError(
 181            "You actually need to change `cfbd_key` to your CFBD API key."
 182        )
 183    elif "Bearer " in real_api_key:
 184        pass
 185    elif "Bearer" in real_api_key:
 186        real_api_key = real_api_key.replace("Bearer", "Bearer ")
 187    else:
 188        real_api_key = "Bearer " + real_api_key
 189    # URL builder
 190    ##########################################################################
 191
 192    if conference is not None:
 193        url += f"?conference={conference}"
 194
 195    headers = {
 196        "Authorization": f"{real_api_key}", "accept": "application/json"
 197    }
 198
 199    response = requests.get(url, headers=headers)
 200
 201    if response.status_code == 200:
 202        pass
 203    elif response.status_code == 401:
 204        raise ConnectionRefusedError(
 205            "Could not connect. The connection was refused.\n" +
 206            "HTTP Status Code 401."
 207        )
 208    else:
 209        raise ConnectionError(
 210            f"Could not connect.\nHTTP Status code {response.status_code}"
 211        )
 212
 213    json_data = response.json()
 214
 215    if return_as_dict is True:
 216        return json_data
 217
 218    for team in tqdm(json_data):
 219        t_team_id = team["id"]
 220        row_df = pd.DataFrame({"team_id": t_team_id}, index=[0])
 221        row_df["school"] = team["school"]
 222        row_df["school_mascot"] = team["mascot"]
 223        row_df["school_abbreviation"] = team["abbreviation"]
 224        row_df["school_alt_name_1"] = team["alt_name1"]
 225        row_df["school_alt_name_2"] = team["alt_name2"]
 226        row_df["school_alt_name_3"] = team["alt_name3"]
 227        row_df["conference"] = team["conference"]
 228        row_df["ncaa_classification"] = team["classification"]
 229        row_df["school_primary_color"] = team["color"]
 230        row_df["school_alt_color"] = team["alt_color"]
 231        try:
 232            row_df["school_primary_logo"] = team["logos"][0]
 233        except:  # noqa: E722
 234            row_df["school_primary_logo"] = np.NaN
 235
 236        try:
 237            row_df["school_primary_logo"] = team["logos"][1]
 238        except:  # noqa: E722
 239            row_df["school_primary_logo"] = np.NaN
 240
 241        row_df["school_twitter"] = team["twitter"]
 242        row_df["home_venue_id"] = team["location"]["venue_id"]
 243        row_df["home_venue_name"] = team["location"]["name"]
 244        row_df["home_venue_capacity"] = team["location"]["capacity"]
 245        row_df["home_venue_year_constructed"] = team["location"]["capacity"]
 246        row_df["is_home_venue_grass"] = team["location"]["grass"]
 247        row_df["is_home_venue_dome"] = team["location"]["dome"]
 248        row_df["city"] = team["location"]["city"]
 249        row_df["state"] = team["location"]["state"]
 250        row_df["zip"] = team["location"]["zip"]
 251        row_df["country_code"] = team["location"]["country_code"]
 252        row_df["timezone"] = team["location"]["timezone"]
 253        row_df["latitude"] = team["location"]["latitude"]
 254        row_df["longitude"] = team["location"]["longitude"]
 255        row_df["elevation"] = team["location"]["elevation"]
 256
 257        teams_df = pd.concat([teams_df, row_df], ignore_index=True)
 258
 259        del row_df
 260        del t_team_id
 261
 262    return teams_df
 263
 264
 265def get_cfbd_fbs_team_list(
 266    api_key: str = None,
 267    api_key_dir: str = None,
 268    season: int = None,
 269    return_as_dict: bool = False,
 270):
 271    """
 272    Allows you to get CFB team information for FBS teams from the CFBD API.
 273
 274    Parameters
 275    ----------
 276    `api_key` (str, optional):
 277        Semi-optional argument.
 278        If `api_key` is null, this function will attempt to load a CFBD API key
 279        from the python environment, or from a file on this computer.
 280        If `api_key` is not null,
 281        this function will automatically assume that the
 282        inputted `api_key` is a valid CFBD API key.
 283
 284    `api_key_dir` (str, optional):
 285        Optional argument.
 286        If `api_key` is set to am empty string, this variable is ignored.
 287        If `api_key_dir` is null, and `api_key` is null,
 288        this function will try to find
 289        a CFBD API key file in this user's home directory.
 290        If `api_key_dir` is set to a string, and `api_key` is null,
 291        this function will assume that `api_key_dir` is a directory,
 292        and will try to find a CFBD API key file in that directory.
 293
 294    `season` (int, optional):
 295        Optional argument.
 296        If you only want CFB team information
 297        for FBS teams in a specific season,
 298        set `season` to that season.
 299
 300    `return_as_dict` (bool, semi-optional):
 301        Semi-optional argument.
 302        If you want this function to return the data
 303        as a dictionary (read: JSON object),
 304        instead of a pandas `DataFrame` object,
 305        set `return_as_dict` to `True`.
 306
 307    Usage
 308    ----------
 309    ```
 310    import time
 311
 312    from cfbd_json_py.teams import get_cfbd_fbs_team_list
 313
 314
 315    cfbd_key = "tigersAreAwesome"  # placeholder for your CFBD API Key.
 316
 317    if cfbd_key != "tigersAreAwesome":
 318        print(
 319            "Using the user's API key declared " +
 320            "in this script for this example."
 321        )
 322
 323        # Get the current list of FBS teams.
 324        print("Get the current list of FBS teams.")
 325        json_data = get_cfbd_fbs_team_list(
 326            api_key=cfbd_key
 327        )
 328        print(json_data)
 329        time.sleep(5)
 330
 331
 332        # Get a list of FBS teams for the 2020 CFB season.
 333        print("Get a list of FBS teams for the 2020 CFB season.")
 334        json_data = get_cfbd_fbs_team_list(
 335            api_key=cfbd_key,
 336            season=2020
 337        )
 338        print(json_data)
 339        time.sleep(5)
 340
 341
 342        # You can also tell this function to just return the API call as
 343        # a Dictionary (read: JSON) object.
 344        print(
 345            "You can also tell this function to just return the API call as " +
 346            "a Dictionary (read: JSON) object."
 347        )
 348        json_data = get_cfbd_fbs_team_list(
 349            api_key=cfbd_key,
 350            season=1990,
 351            return_as_dict=True
 352        )
 353        print(json_data)
 354
 355    else:
 356        # Alternatively, if the CFBD API key exists in this python environment,
 357        # or it's been set by cfbd_json_py.utls.set_cfbd_api_token(),
 358        # you could just call these functions directly,
 359        # without setting the API key
 360        # in the script.
 361        print(
 362            "Using the user's API key supposedly loaded into " +
 363            "this python environment for this example."
 364        )
 365
 366        # Get the current list of FBS teams.
 367        print("Get the current list of FBS teams.")
 368        json_data = get_cfbd_fbs_team_list()
 369        print(json_data)
 370        time.sleep(5)
 371
 372
 373        # Get a list of FBS teams for the 2020 CFB season.
 374        print("Get a list of FBS teams for the 2020 CFB season.")
 375        json_data = get_cfbd_fbs_team_list(
 376            season=2020
 377        )
 378        print(json_data)
 379        time.sleep(5)
 380
 381
 382        # You can also tell this function to just return the API call as
 383        # a Dictionary (read: JSON) object.
 384        print(
 385            "You can also tell this function to just return the API call " +
 386            "as a Dictionary (read: JSON) object."
 387        )
 388        json_data = get_cfbd_fbs_team_list(
 389            season=1990,
 390            return_as_dict=True
 391        )
 392        print(json_data)
 393    ```
 394    Returns
 395    ----------
 396    A pandas `DataFrame` object with CFB team information,
 397    or (if `return_as_dict` is set to `True`)
 398    a dictionary object with CFB team information.
 399
 400    """
 401    warnings.simplefilter(action="ignore", category=FutureWarning)
 402
 403    teams_df = pd.DataFrame()
 404    row_df = pd.DataFrame()
 405    url = "https://api.collegefootballdata.com/teams/fbs"
 406
 407    ##########################################################################
 408
 409    if api_key is not None:
 410        real_api_key = api_key
 411        del api_key
 412    else:
 413        real_api_key = get_cfbd_api_token(api_key_dir=api_key_dir)
 414
 415    if real_api_key == "tigersAreAwesome":
 416        raise ValueError(
 417            "You actually need to change `cfbd_key` to your CFBD API key."
 418        )
 419    elif "Bearer " in real_api_key:
 420        pass
 421    elif "Bearer" in real_api_key:
 422        real_api_key = real_api_key.replace("Bearer", "Bearer ")
 423    else:
 424        real_api_key = "Bearer " + real_api_key
 425
 426    # URL builder
 427    ##########################################################################
 428
 429    if season is not None:
 430        url += f"?year={season}"
 431
 432    headers = {
 433        "Authorization": f"{real_api_key}", "accept": "application/json"
 434    }
 435
 436    response = requests.get(url, headers=headers)
 437
 438    if response.status_code == 200:
 439        pass
 440    elif response.status_code == 401:
 441        raise ConnectionRefusedError(
 442            "Could not connect. The connection was refused.\n" +
 443            "HTTP Status Code 401."
 444        )
 445    else:
 446        raise ConnectionError(
 447            f"Could not connect.\nHTTP Status code {response.status_code}"
 448        )
 449
 450    json_data = response.json()
 451
 452    if return_as_dict is True:
 453        return json_data
 454
 455    for team in tqdm(json_data):
 456        t_team_id = team["id"]
 457        row_df = pd.DataFrame({"team_id": t_team_id}, index=[0])
 458        row_df["school"] = team["school"]
 459        row_df["school_mascot"] = team["mascot"]
 460        row_df["school_abbreviation"] = team["abbreviation"]
 461        row_df["school_alt_name_1"] = team["alt_name1"]
 462        row_df["school_alt_name_2"] = team["alt_name2"]
 463        row_df["school_alt_name_3"] = team["alt_name3"]
 464        row_df["conference"] = team["conference"]
 465        # row_df['ncaa_classification'] = team['classification']
 466        row_df["ncaa_classification"] = "fbs"
 467        row_df["school_primary_color"] = team["color"]
 468        row_df["school_alt_color"] = team["alt_color"]
 469        try:
 470            row_df["school_primary_logo"] = team["logos"][0]
 471        except:  # noqa: E722
 472            row_df["school_primary_logo"] = np.NaN
 473
 474        try:
 475            row_df["school_primary_logo"] = team["logos"][1]
 476        except:  # noqa: E722
 477            row_df["school_primary_logo"] = np.NaN
 478
 479        row_df["school_twitter"] = team["twitter"]
 480        row_df["home_venue_id"] = team["location"]["venue_id"]
 481        row_df["home_venue_name"] = team["location"]["name"]
 482        row_df["home_venue_capacity"] = team["location"]["capacity"]
 483        row_df["home_venue_year_constructed"] = team["location"]["capacity"]
 484        row_df["is_home_venue_grass"] = team["location"]["grass"]
 485        row_df["is_home_venue_dome"] = team["location"]["dome"]
 486        row_df["city"] = team["location"]["city"]
 487        row_df["state"] = team["location"]["state"]
 488        row_df["zip"] = team["location"]["zip"]
 489        row_df["country_code"] = team["location"]["country_code"]
 490        row_df["timezone"] = team["location"]["timezone"]
 491        row_df["latitude"] = team["location"]["latitude"]
 492        row_df["longitude"] = team["location"]["longitude"]
 493        row_df["elevation"] = team["location"]["elevation"]
 494
 495        teams_df = pd.concat([teams_df, row_df], ignore_index=True)
 496
 497        del row_df
 498        del t_team_id
 499
 500    return teams_df
 501
 502
 503def get_cfbd_team_rosters(
 504    api_key: str = None,
 505    api_key_dir: str = None,
 506    team: str = None,
 507    season: int = None,
 508    return_as_dict: bool = False,
 509):
 510    """
 511    Allows you to get CFB team roster data for FBS teams from the CFBD API.
 512
 513    Parameters
 514    ----------
 515    `api_key` (str, optional):
 516        Semi-optional argument.
 517        If `api_key` is null, this function will attempt to load a CFBD API key
 518        from the python environment, or from a file on this computer.
 519        If `api_key` is not null,
 520        this function will automatically assume that the
 521        inputted `api_key` is a valid CFBD API key.
 522
 523    `api_key_dir` (str, optional):
 524        Optional argument.
 525        If `api_key` is set to am empty string, this variable is ignored.
 526        If `api_key_dir` is null, and `api_key` is null,
 527        this function will try to find
 528        a CFBD API key file in this user's home directory.
 529        If `api_key_dir` is set to a string, and `api_key` is null,
 530        this function will assume that `api_key_dir` is a directory,
 531        and will try to find a CFBD API key file in that directory.
 532
 533    `season` (int, optional):
 534        Optional argument.
 535        If you only want CFB team roster data
 536        for FBS teams in a specific season,
 537        set `season` to that season.
 538
 539    `team` (str, optional):
 540        Optional argument.
 541        If you only want CFB team roster data for a specific CFB team,
 542        set `team` to that CFB team's name.
 543
 544    `return_as_dict` (bool, semi-optional):
 545        Semi-optional argument.
 546        If you want this function to return
 547        the data as a dictionary (read: JSON object),
 548        instead of a pandas `DataFrame` object,
 549        set `return_as_dict` to `True`.
 550
 551    Usage
 552    ----------
 553    ```
 554    import time
 555
 556    from cfbd_json_py.teams import get_cfbd_team_rosters
 557
 558
 559    cfbd_key = "tigersAreAwesome"  # placeholder for your CFBD API Key.
 560
 561    if cfbd_key != "tigersAreAwesome":
 562        print(
 563            "Using the user's API key declared in this script " +
 564            "for this example."
 565        )
 566
 567        # Get the team roster for the 2019 LSU Tigers Football Team.
 568        print("Get the team rosters for the 2020 CFB season.")
 569        json_data = get_cfbd_team_rosters(
 570            api_key=cfbd_key,
 571            season=2020,
 572            team="LSU"
 573        )
 574        print(json_data)
 575        time.sleep(5)
 576
 577        # Get the team rosters for the 2020 CFB season.
 578        print("Get the team rosters for the 2020 CFB season.")
 579        json_data = get_cfbd_team_rosters(
 580            api_key=cfbd_key,
 581            season=2020
 582        )
 583        print(json_data)
 584        time.sleep(5)
 585
 586        # Get a list of known players with
 587        # the Ohio State Buckeyes Football Team.
 588        print(
 589            "Get a list of known players with " +
 590            "the Ohio State Buckeyes Football Team."
 591        )
 592        json_data = get_cfbd_team_rosters(
 593            api_key=cfbd_key,
 594            team="Ohio State"
 595        )
 596        print(json_data)
 597        time.sleep(5)
 598
 599
 600        # You can also tell this function to just return the API call as
 601        # a Dictionary (read: JSON) object.
 602        print(
 603            "You can also tell this function to just return the API call " +
 604            "as a Dictionary (read: JSON) object."
 605        )
 606        json_data = get_cfbd_team_rosters(
 607            api_key=cfbd_key,
 608            season=2015,
 609            team="LSU",
 610            return_as_dict=True
 611        )
 612        print(json_data)
 613
 614    else:
 615        # Alternatively, if the CFBD API key exists in this python environment,
 616        # or it's been set by cfbd_json_py.utls.set_cfbd_api_token(),
 617        # you could just call these functions directly,
 618        # without setting the API key in the script.
 619        print(
 620            "Using the user's API key supposedly loaded " +
 621            "into this python environment for this example."
 622        )
 623
 624
 625        # Get the team roster for the 2019 LSU Tigers Football Team.
 626        print("Get the team roster for the 2019 LSU Tigers Football Team.")
 627        json_data = get_cfbd_team_rosters(
 628            season=2020,
 629            team="LSU"
 630        )
 631        print(json_data)
 632        time.sleep(5)
 633
 634        # Get the team rosters for the 2020 CFB season.
 635        print("Get the team rosters for the 2020 CFB season.")
 636        json_data = get_cfbd_team_rosters(
 637            season=2020
 638        )
 639        print(json_data)
 640        time.sleep(5)
 641
 642        # Get a list of known players with
 643        # the Ohio State Buckeyes Football Team.
 644        print(
 645            "Get a list of known players with " +
 646            "the Ohio State Buckeyes Football Team."
 647        )
 648        json_data = get_cfbd_team_rosters(
 649            team="Ohio State"
 650        )
 651        print(json_data)
 652        time.sleep(5)
 653
 654
 655        # You can also tell this function to just return the API call as
 656        # a Dictionary (read: JSON) object.
 657        print(
 658            "You can also tell this function to just return the API call " +
 659            "as a Dictionary (read: JSON) object."
 660        )
 661        json_data = get_cfbd_team_rosters(
 662            season=2015,
 663            team="LSU",
 664            return_as_dict=True
 665        )
 666        print(json_data)
 667
 668    ```
 669    Returns
 670    ----------
 671    A pandas `DataFrame` object with CFB team roster data,
 672    or (if `return_as_dict` is set to `True`)
 673    a dictionary object with CFB team roster data.
 674
 675    """
 676    now = datetime.now()
 677    roster_df = pd.DataFrame()
 678    # row_df = pd.DataFrame()
 679    url = "https://api.collegefootballdata.com/roster"
 680
 681    ##########################################################################
 682
 683    if api_key is not None:
 684        real_api_key = api_key
 685        del api_key
 686    else:
 687        real_api_key = get_cfbd_api_token(api_key_dir=api_key_dir)
 688
 689    if real_api_key == "tigersAreAwesome":
 690        raise ValueError(
 691            "You actually need to change `cfbd_key` to your CFBD API key."
 692        )
 693    elif "Bearer " in real_api_key:
 694        pass
 695    elif "Bearer" in real_api_key:
 696        real_api_key = real_api_key.replace("Bearer", "Bearer ")
 697    else:
 698        real_api_key = "Bearer " + real_api_key
 699
 700    if season is not None and season > (now.year + 1):
 701        raise ValueError(f"`season` cannot be greater than {season}.")
 702    elif season is not None and season < 1869:
 703        raise ValueError("`season` cannot be less than 1869.")
 704
 705    # URL builder
 706    ##########################################################################
 707
 708    url_elements = 0
 709
 710    if season is not None and url_elements == 0:
 711        url += f"?year={season}"
 712        url_elements += 1
 713    elif season is not None:
 714        url += f"&year={season}"
 715        url_elements += 1
 716
 717    if team is not None and url_elements == 0:
 718        url += f"?team={team}"
 719        url_elements += 1
 720    elif team is not None:
 721        url += f"&team={team}"
 722        url_elements += 1
 723
 724    headers = {
 725        "Authorization": f"{real_api_key}",
 726        "accept": "application/json"
 727    }
 728
 729    response = requests.get(url, headers=headers)
 730
 731    if response.status_code == 200:
 732        pass
 733    elif response.status_code == 401:
 734        raise ConnectionRefusedError(
 735            "Could not connect. The connection was refused." +
 736            "\nHTTP Status Code 401."
 737        )
 738    else:
 739        raise ConnectionError(
 740            f"Could not connect.\nHTTP Status code {response.status_code}"
 741        )
 742
 743    json_data = response.json()
 744
 745    if return_as_dict is True:
 746        return json_data
 747
 748    roster_df = pd.DataFrame(json_data)
 749    return roster_df
 750
 751
 752def get_cfbd_team_talent_rankings(
 753    api_key: str = None,
 754    api_key_dir: str = None,
 755    season: int = None,
 756    return_as_dict: bool = False,
 757):
 758    """
 759    Get a list of teams, and their overall talent rankings, from the CFBD API.
 760
 761    Parameters
 762    ----------
 763    `api_key` (str, optional):
 764        Semi-optional argument.
 765        If `api_key` is null, this function will attempt to load a CFBD API key
 766        from the python environment, or from a file on this computer.
 767        If `api_key` is not null,
 768        this function will automatically assume that the
 769        inputted `api_key` is a valid CFBD API key.
 770
 771    `api_key_dir` (str, optional):
 772        Optional argument.
 773        If `api_key` is set to am empty string, this variable is ignored.
 774        If `api_key_dir` is null, and `api_key` is null,
 775        this function will try to find
 776        a CFBD API key file in this user's home directory.
 777        If `api_key_dir` is set to a string, and `api_key` is null,
 778        this function will assume that `api_key_dir` is a directory,
 779        and will try to find a CFBD API key file in that directory.
 780
 781    `season` (int, optional):
 782        Optional argument.
 783        If you only want CFB team talent ranking data
 784        for FBS teams in a specific season,
 785        set `season` to that season.
 786
 787    `return_as_dict` (bool, semi-optional):
 788        Semi-optional argument.
 789        If you want this function to return
 790        the data as a dictionary (read: JSON object),
 791        instead of a pandas `DataFrame` object,
 792        set `return_as_dict` to `True`.
 793
 794    Usage
 795    ----------
 796    ```
 797    import time
 798
 799    from cfbd_json_py.teams import get_cfbd_team_talent_rankings
 800
 801
 802    cfbd_key = "tigersAreAwesome"  # placeholder for your CFBD API Key.
 803
 804    if cfbd_key != "tigersAreAwesome":
 805        print(
 806            "Using the user's API key declared in this script " +
 807            "for this example."
 808        )
 809
 810        # Get team talent rankings data for the 2020 CFB season.
 811        print("Get team talent rankings data for the 2020 CFB season.")
 812        json_data = get_cfbd_team_talent_rankings(
 813            api_key=cfbd_key,
 814            season=2020
 815        )
 816        print(json_data)
 817        time.sleep(5)
 818
 819        # Get team talent rankings data for as many seasons as possible.
 820        print("Get team talent rankings data for as many seasons as possible.")
 821        json_data = get_cfbd_team_talent_rankings(
 822            api_key=cfbd_key
 823        )
 824        print(json_data)
 825        time.sleep(5)
 826
 827        # You can also tell this function to just return the API call as
 828        # a Dictionary (read: JSON) object.
 829        print(
 830            "You can also tell this function to just return the API call " +
 831            "as a Dictionary (read: JSON) object."
 832        )
 833        json_data = get_cfbd_team_talent_rankings(
 834            api_key=cfbd_key,
 835            season=2015,
 836            return_as_dict=True
 837        )
 838        print(json_data)
 839
 840    else:
 841        # Alternatively, if the CFBD API key exists in this python environment,
 842        # or it's been set by cfbd_json_py.utls.set_cfbd_api_token(),
 843        # you could just call these functions directly,
 844        # without setting the API key in the script.
 845        print(
 846            "Using the user's API key supposedly loaded " +
 847            "into this python environment for this example."
 848        )
 849
 850
 851        # Get team talent rankings data for the 2020 CFB season.
 852        print("Get team talent rankings data for the 2020 CFB season.")
 853        json_data = get_cfbd_team_talent_rankings(
 854            season=2020
 855        )
 856        print(json_data)
 857        time.sleep(5)
 858
 859        # Get team talent rankings data for as many seasons as possible.
 860        print("Get team talent rankings data for as many seasons as possible.")
 861        json_data = get_cfbd_team_talent_rankings()
 862        print(json_data)
 863        time.sleep(5)
 864
 865        # You can also tell this function to just return the API call as
 866        # a Dictionary (read: JSON) object.
 867        print(
 868            "You can also tell this function to just return the API call " +
 869            "as a Dictionary (read: JSON) object."
 870        )
 871        json_data = get_cfbd_team_talent_rankings(
 872            season=2015,
 873            return_as_dict=True
 874        )
 875        print(json_data)
 876
 877    ```
 878    Returns
 879    ----------
 880    A pandas `DataFrame` object with CFB team talent ratings data,
 881    or (if `return_as_dict` is set to `True`)
 882    a dictionary object with CFB team talent ratings data.
 883    """
 884    now = datetime.now()
 885    teams_df = pd.DataFrame()
 886    # row_df = pd.DataFrame()
 887    url = "https://api.collegefootballdata.com/talent"
 888
 889    ##########################################################################
 890
 891    if api_key is not None:
 892        real_api_key = api_key
 893        del api_key
 894    else:
 895        real_api_key = get_cfbd_api_token(api_key_dir=api_key_dir)
 896
 897    if real_api_key == "tigersAreAwesome":
 898        raise ValueError(
 899            "You actually need to change `cfbd_key` to your CFBD API key."
 900        )
 901    elif "Bearer " in real_api_key:
 902        pass
 903    elif "Bearer" in real_api_key:
 904        real_api_key = real_api_key.replace("Bearer", "Bearer ")
 905    else:
 906        real_api_key = "Bearer " + real_api_key
 907
 908    if season is not None and season > (now.year + 1):
 909        raise ValueError(f"`season` cannot be greater than {season}.")
 910    elif season is not None and season < 1869:
 911        raise ValueError("`season` cannot be less than 1869.")
 912
 913    # URL builder
 914    ##########################################################################
 915
 916    if season is not None:
 917        url += f"?year={season}"
 918
 919    headers = {
 920        "Authorization": f"{real_api_key}",
 921        "accept": "application/json"
 922    }
 923
 924    response = requests.get(url, headers=headers)
 925
 926    if response.status_code == 200:
 927        pass
 928    elif response.status_code == 401:
 929        raise ConnectionRefusedError(
 930            "Could not connect. The connection was refused." +
 931            "\nHTTP Status Code 401."
 932        )
 933    else:
 934        raise ConnectionError(
 935            f"Could not connect.\nHTTP Status code {response.status_code}"
 936        )
 937
 938    json_data = response.json()
 939
 940    if return_as_dict is True:
 941        return json_data
 942
 943    teams_df = pd.DataFrame(json_data)
 944
 945    return teams_df
 946
 947
 948def get_cfbd_team_matchup_history(
 949    team_1: str,
 950    team_2: str,
 951    api_key: str = None,
 952    api_key_dir: str = None,
 953    min_season: int = None,
 954    max_season: int = None,
 955    return_as_dict: bool = False,
 956):
 957    """
 958    Get a list of matchups between two teams, from the CFBD API.
 959
 960    Parameters
 961    ----------
 962    `team_1` (str, mandatory):
 963        Mandatory argument.
 964        This is the name of the **first** team in this matchup.
 965
 966    `team_1` (str, mandatory):
 967        Mandatory argument.
 968        This is the name of the **second** team in this matchup.
 969
 970    `api_key` (str, optional):
 971        Semi-optional argument.
 972        If `api_key` is null, this function will attempt to load a CFBD API key
 973        from the python environment, or from a file on this computer.
 974        If `api_key` is not null,
 975        this function will automatically assume that the
 976        inputted `api_key` is a valid CFBD API key.
 977
 978    `api_key_dir` (str, optional):
 979        Optional argument.
 980        If `api_key` is set to am empty string, this variable is ignored.
 981        If `api_key_dir` is null, and `api_key` is null,
 982        this function will try to find
 983        a CFBD API key file in this user's home directory.
 984        If `api_key_dir` is set to a string, and `api_key` is null,
 985        this function will assume that `api_key_dir` is a directory,
 986        and will try to find a CFBD API key file in that directory.
 987
 988    `min_season` (int, optional):
 989        Optional argument.
 990        If you only want matchups starting in a specific season,
 991        set `min_season` to that season.
 992
 993    `max_season` (int, optional):
 994        Optional argument.
 995        If you only want matchups up to a specific season,
 996        set `max_season` to that season.
 997
 998    `return_as_dict` (bool, semi-optional):
 999        Semi-optional argument.
1000        If you want this function to return
1001        the data as a dictionary (read: JSON object),
1002        instead of a pandas `DataFrame` object,
1003        set `return_as_dict` to `True`.
1004
1005    Usage
1006    ----------
1007    ```
1008    import time
1009
1010    from cfbd_json_py.teams import get_cfbd_team_matchup_history
1011
1012
1013    cfbd_key = "tigersAreAwesome"  # placeholder for your CFBD API Key.
1014
1015    if cfbd_key != "tigersAreAwesome":
1016        print(
1017            "Using the user's API key declared in this script " +
1018            "for this example."
1019        )
1020
1021        # Get the matchup history between the University of Cincinnati
1022        # and the Miami (OH) Redhawks football teams.
1023        print(
1024            "Get the matchup history between the University of Cincinnati " +
1025            "and the Miami (OH) Redhawks football teams."
1026        )
1027        json_data = get_cfbd_team_matchup_history(
1028            api_key=cfbd_key,
1029            team_1="Cincinnati",
1030            team_2="Miami (OH)"
1031        )
1032        print(json_data)
1033        time.sleep(5)
1034
1035        # Get the matchup history between the Ohio State Buckeyes
1036        # and the Michigan Wolverines football teams,
1037        # starting in 2002.
1038        print(
1039            "Get the matchup history between the Ohio State Buckeyes " +
1040            "and the University of Michigan Wolverines " +
1041            "football teams, starting in 2002."
1042        )
1043        json_data = get_cfbd_team_matchup_history(
1044            api_key=cfbd_key,
1045            team_1="Ohio State",
1046            team_2="Michigan",
1047            min_season=2002
1048        )
1049        print(json_data)
1050        time.sleep(5)
1051
1052        # Get the matchup history between the Ohio Bobcats
1053        # and the Miami (OH) Redhawks football teams,
1054        # starting in 1990 and ending in 2005.
1055        print(
1056            "Get the matchup history between the University of Cincinnati " +
1057            "and the Miami (OH) Redhawks football teams."
1058        )
1059        json_data = get_cfbd_team_matchup_history(
1060            api_key=cfbd_key,
1061            team_1="Ohio",
1062            team_2="Miami (OH)",
1063            min_season=1990,
1064            max_season=2005
1065        )
1066        print(json_data)
1067        time.sleep(5)
1068
1069        # You can also tell this function to just return the API call as
1070        # a Dictionary (read: JSON) object.
1071        print(
1072            "You can also tell this function to just return the API call " +
1073            "as a Dictionary (read: JSON) object."
1074        )
1075        json_data = get_cfbd_team_matchup_history(
1076            api_key=cfbd_key,
1077            team_1="Cincinnati",
1078            team_2="Miami (OH)",
1079            min_season=2020,
1080            return_as_dict=True
1081        )
1082        print(json_data)
1083
1084    else:
1085        # Alternatively, if the CFBD API key exists in this python environment,
1086        # or it's been set by cfbd_json_py.utls.set_cfbd_api_token(),
1087        # you could just call these functions directly,
1088        # without setting the API key in the script.
1089        print(
1090            "Using the user's API key supposedly loaded " +
1091            "into this python environment for this example."
1092        )
1093
1094
1095        # Get the matchup history between the University of Cincinnati
1096        # and the Miami (OH) Redhawks football teams.
1097        print(
1098            "Get the matchup history between the University of Cincinnati " +
1099            "and the Miami (OH) Redhawks football teams."
1100        )
1101        json_data = get_cfbd_team_matchup_history(
1102            team_1="Cincinnati",
1103            team_2="Miami (OH)"
1104        )
1105        print(json_data)
1106        time.sleep(5)
1107
1108        # Get the matchup history between the Ohio State Buckeyes
1109        # and the Michigan Wolverines football teams,
1110        # starting in 2002.
1111        print(
1112            "Get the matchup history between the Ohio State Buckeyes " +
1113            "and the University of Michigan Wolverines " +
1114            "football teams, starting in 2002."
1115        )
1116        json_data = get_cfbd_team_matchup_history(
1117            team_1="Ohio State",
1118            team_2="Michigan",
1119            min_season=2002
1120        )
1121        print(json_data)
1122        time.sleep(5)
1123
1124        # Get the matchup history between the Ohio Bobcats
1125        # and the Miami (OH) Redhawks football teams,
1126        # starting in 1990 and ending in 2005.
1127        print(
1128            "Get the matchup history between the University of Cincinnati " +
1129            "and the Miami (OH) Redhawks football teams."
1130        )
1131        json_data = get_cfbd_team_matchup_history(
1132            team_1="Ohio",
1133            team_2="Miami (OH)",
1134            min_season=1990,
1135            max_season=2005
1136        )
1137        print(json_data)
1138        time.sleep(5)
1139
1140        # You can also tell this function to just return the API call as
1141        # a Dictionary (read: JSON) object.
1142        print(
1143            "You can also tell this function to just return the API call " +
1144            "as a Dictionary (read: JSON) object."
1145        )
1146        json_data = get_cfbd_team_matchup_history(
1147            team_1="Cincinnati",
1148            team_2="Miami (OH)",
1149            min_season=2020,
1150            return_as_dict=True
1151        )
1152        print(json_data)
1153    ```
1154    Returns
1155    ----------
1156    A pandas `DataFrame` object with CFB team matchup data,
1157    or (if `return_as_dict` is set to `True`)
1158    a dictionary object with CFB team matchup data.
1159    """
1160    now = datetime.now()
1161    matchups_df = pd.DataFrame()
1162    row_df = pd.DataFrame()
1163    url = "https://api.collegefootballdata.com/teams/matchup"
1164
1165    ##########################################################################
1166
1167    if api_key is not None:
1168        real_api_key = api_key
1169        del api_key
1170    else:
1171        real_api_key = get_cfbd_api_token(api_key_dir=api_key_dir)
1172
1173    if real_api_key == "tigersAreAwesome":
1174        raise ValueError(
1175            "You actually need to change `cfbd_key` to your CFBD API key."
1176        )
1177    elif "Bearer " in real_api_key:
1178        pass
1179    elif "Bearer" in real_api_key:
1180        real_api_key = real_api_key.replace("Bearer", "Bearer ")
1181    else:
1182        real_api_key = "Bearer " + real_api_key
1183
1184    if min_season is not None and min_season > (now.year + 1):
1185        raise ValueError(f"`min_season` cannot be greater than {min_season}.")
1186    elif min_season is not None and min_season < 1869:
1187        raise ValueError("`min_season` cannot be less than 1869.")
1188
1189    if max_season is not None and max_season > (now.year + 1):
1190        raise ValueError(f"`max_season` cannot be greater than {max_season}.")
1191    elif max_season is not None and max_season < 1869:
1192        raise ValueError("`max_season` cannot be less than 1869.")
1193
1194    # URL builder
1195    ##########################################################################
1196
1197    # Required by the API:
1198    url += f"?team1={team_1}&team2={team_2}"
1199
1200    if min_season is not None:
1201        url += f"&minYear={min_season}"
1202
1203    if max_season is not None:
1204        url += f"&maxYear={max_season}"
1205
1206    headers = {
1207        "Authorization": f"{real_api_key}",
1208        "accept": "application/json"
1209    }
1210
1211    response = requests.get(url, headers=headers)
1212
1213    if response.status_code == 200:
1214        pass
1215    elif response.status_code == 401:
1216        raise ConnectionRefusedError(
1217            "Could not connect. The connection was refused." +
1218            "\nHTTP Status Code 401."
1219        )
1220    else:
1221        raise ConnectionError(
1222            f"Could not connect.\nHTTP Status code {response.status_code}"
1223        )
1224
1225    json_data = response.json()
1226
1227    if return_as_dict is True:
1228        return json_data
1229
1230    team_1_wins = json_data["team1Wins"]
1231    team_2_wins = json_data["team2Wins"]
1232    total_ties = json_data["ties"]
1233
1234    for game in tqdm(json_data["games"]):
1235        row_df = pd.DataFrame(
1236            {
1237                "team_1": team_1,
1238                "team_2": team_2,
1239                "start_year": min_season,
1240                "end_year": max_season,
1241                "team_1_wins": team_1_wins,
1242                "team_2_wins": team_2_wins,
1243                "ties": total_ties,
1244            },
1245            index=[0],
1246        )
1247        row_df["season"] = game["season"]
1248        row_df["week"] = game["week"]
1249        row_df["season_type"] = game["seasonType"]
1250        row_df["date"] = game["date"]
1251        row_df["is_neutral_site_game"] = game["neutralSite"]
1252        row_df["venue"] = game["venue"]
1253        row_df["home_team"] = game["homeTeam"]
1254        row_df["home_score"] = game["homeScore"]
1255        row_df["away_team"] = game["awayTeam"]
1256        row_df["away_score"] = game["awayScore"]
1257        row_df["winner"] = game["winner"]
1258
1259        matchups_df = pd.concat([matchups_df, row_df], ignore_index=True)
1260        del row_df
1261
1262    return matchups_df