cfbd_json_py.recruiting

   1# Creation Date: 08/30/2023 01:13 EDT
   2# Last Updated Date: 09/16/2024 06:10 PM EDT
   3# Author: Joseph Armstrong (armstrongjoseph08@gmail.com)
   4# File Name: recruiting.py
   5# Purpose: Houses functions pertaining to CFB recruiting data
   6#    within the CFBD API.
   7###############################################################################
   8
   9import logging
  10from datetime import datetime
  11
  12import pandas as pd
  13import requests
  14
  15from cfbd_json_py.utls import get_cfbd_api_token
  16
  17
  18def get_cfbd_player_recruit_ratings(
  19    api_key: str = None,
  20    api_key_dir: str = None,
  21    season: int = None,
  22    team: str = None,
  23    # `year` and/or `team` need to be not null for this function to work.
  24    recruit_classification: str = None,
  25    # Can be "HighSchool", "JUCO", or "PrepSchool"
  26    position: str = None,
  27    state: str = None,
  28    return_as_dict: bool = False,
  29):
  30    """
  31    Allows you to get CFB player recruiting data from the CFBD API.
  32
  33    Parameters
  34    ----------
  35
  36    `api_key` (str, optional):
  37        Semi-optional argument.
  38        If `api_key` is null, this function will attempt to load a CFBD API key
  39        from the python environment, or from a file on this computer.
  40        If `api_key` is not null,
  41        this function will automatically assume that the
  42        inputted `api_key` is a valid CFBD API key.
  43
  44    `api_key_dir` (str, optional):
  45        Optional argument.
  46        If `api_key` is set to am empty string, this variable is ignored.
  47        If `api_key_dir` is null, and `api_key` is null,
  48        this function will try to find
  49        a CFBD API key file in this user's home directory.
  50        If `api_key_dir` is set to a string, and `api_key` is null,
  51        this function will assume that `api_key_dir` is a directory,
  52        and will try to find a CFBD API key file in that directory.
  53
  54    `season` (int, semi-mandatory):
  55        Semi-required argument.
  56        Specifies the season you want CFB recruiting data from.
  57        This must be specified, otherwise this package, and by extension
  58        the CFBD API, will not accept the request to get CFB recruiting data.
  59        This or `team` must be set to a valid non-null variable
  60        for this to function.
  61
  62    `team` (str, semi-mandatory):
  63        Semi-required argument.
  64        Specifies the season you want CFB recruiting data from.
  65        This must be specified, otherwise this package, and by extension
  66        the CFBD API, will not accept the request to get CFB recruiting data.
  67        This or `season` must be set to a valid non-null variable
  68        for this to function.
  69
  70    `recruit_classification` (str, optional):
  71        Optional argument.
  72        By default, this is sent to `None`,
  73        so one can get all recruits from a given season and/or team.
  74
  75        If you want to filter by what type of recruit,
  76        the following values are valid for `recruit_classification`:
  77        - `HighSchool`: Exactly what it says on the tin. These are HS recruits.
  78        - `JUCO`: JUnior COllege recruits.
  79            These are recruits who are transferring from a
  80            junior college to an NCAA college.
  81        - `PrepSchool`: College Prep school recruits.
  82            These are recruits from places such as
  83            the Fork Union Military Academy in Fort Union, VA
  84            or Palmetto Prep in Columbia, SC.
  85
  86    `position` (str, optional):
  87        Optional argument.
  88        If you ony want recruits from a specific position,
  89        set `position` to that position's acronym.
  90        Acronyms such as `DUAL` for "DUAL-threat QBs"
  91        and `APB` for "All-Purpose running Backs" are valid inputs.
  92
  93    `state` (str, optional):
  94        Optional argument.
  95        If you only want recruits from a specific state in the United Sates,
  96        set `state` to he USPS abbreviation of that state
  97        (like `OH` for Ohio, or `IN` for Indiana).
  98
  99    `return_as_dict` (bool, semi-optional):
 100        Semi-optional argument.
 101        If you want this function to return
 102        the data as a dictionary (read: JSON object),
 103        instead of a pandas `DataFrame` object,
 104        set `return_as_dict` to `True`.
 105
 106    Usage
 107    ----------
 108    ```
 109    import time
 110
 111    from cfbd_json_py.recruiting import get_cfbd_player_recruit_ratings
 112
 113
 114    cfbd_key = "tigersAreAwesome"  # placeholder for your CFBD API Key.
 115
 116    if cfbd_key != "tigersAreAwesome":
 117        print(
 118            "Using the user's API key declared in this script " +
 119            "for this example."
 120        )
 121
 122        # Get a list of all recruits for the 2020 recruiting class.
 123        print("Get a list of all recruits for the 2020 recruiting class.")
 124        json_data = get_cfbd_player_recruit_ratings(
 125            api_key=cfbd_key,
 126            season=2020
 127        )
 128        print(json_data)
 129        time.sleep(5)
 130
 131        # Get a list of all recruits from
 132        # the 2020 Ohio State Buckeyes recruiting class.
 133        print(
 134            "Get a list of all recruits from " +
 135            "the 2020 Ohio State Buckeyes recruiting class."
 136        )
 137        json_data = get_cfbd_player_recruit_ratings(
 138            api_key=cfbd_key,
 139            season=2020,
 140            team="Ohio State"
 141        )
 142        print(json_data)
 143        time.sleep(5)
 144
 145        # Get a list of all recruits JUCO recruits for
 146        # the 2019 recruiting class.
 147        print(
 148            "Get a list of all recruits JUCO recruits for " +
 149            "the 2019 recruiting class."
 150        )
 151        json_data = get_cfbd_player_recruit_ratings(
 152            api_key=cfbd_key,
 153            season=2019,
 154            recruit_classification="JUCO"
 155        )
 156        print(json_data)
 157        time.sleep(5)
 158
 159        # Get a list of all wide receiver recruits
 160        # from the 2018 recruiting class.
 161        print(
 162            "Get a list of all wide receiver recruits " +
 163            "from the 2018 recruiting class."
 164        )
 165        json_data = get_cfbd_player_recruit_ratings(
 166            api_key=cfbd_key,
 167            season=2020,
 168            position="WR"
 169        )
 170        print(json_data)
 171        time.sleep(5)
 172
 173        # Get a list of all recruits from
 174        # the state of Idaho in the 2017 recruiting class.
 175        print(
 176            "Get a list of all recruits " +
 177            "from the state of Idaho in the 2017 recruiting class."
 178        )
 179        json_data = get_cfbd_player_recruit_ratings(
 180            api_key=cfbd_key,
 181            season=2020,
 182            state="ID"
 183        )
 184        print(json_data)
 185        time.sleep(5)
 186
 187        # You can also tell this function to just return the API call as
 188        # a Dictionary (read: JSON) object.
 189        print(
 190            "You can also tell this function to just return the API call " +
 191            "as a Dictionary (read: JSON) object."
 192        )
 193        json_data = get_cfbd_player_recruit_ratings(
 194            api_key=cfbd_key,
 195            season=2020,
 196            team="Ohio",
 197            return_as_dict=True
 198        )
 199        print(json_data)
 200
 201    else:
 202        # Alternatively, if the CFBD API key exists in this python environment,
 203        # or it's been set by cfbd_json_py.utls.set_cfbd_api_token(),
 204        # you could just call these functions directly,
 205        # without setting the API key in the script.
 206        print(
 207            "Using the user's API key supposedly loaded " +
 208            "into this python environment for this example."
 209        )
 210
 211
 212        # Get a list of all recruits for the 2020 recruiting class.
 213        print("Get a list of all recruits for the 2020 recruiting class.")
 214        json_data = get_cfbd_player_recruit_ratings(
 215            season=2020
 216        )
 217        print(json_data)
 218        time.sleep(5)
 219
 220        # Get a list of all recruits from
 221        # the 2020 Ohio State Buckeyes recruiting class.
 222        print(
 223            "Get a list of all recruits from " +
 224            "the 2020 Ohio State Buckeyes recruiting class."
 225        )
 226        json_data = get_cfbd_player_recruit_ratings(
 227            season=2020,
 228            team="Ohio State"
 229        )
 230        print(json_data)
 231        time.sleep(5)
 232
 233        # Get a list of all recruits JUCO recruits for
 234        # the 2019 recruiting class.
 235        print(
 236            "Get a list of all recruits JUCO recruits for " +
 237            "the 2019 recruiting class."
 238        )
 239        json_data = get_cfbd_player_recruit_ratings(
 240            season=2019,
 241            recruit_classification="JUCO"
 242        )
 243        print(json_data)
 244        time.sleep(5)
 245
 246        # Get a list of all wide receiver recruits
 247        # from the 2018 recruiting class.
 248        print(
 249            "Get a list of all wide receiver recruits " +
 250            "from the 2018 recruiting class."
 251        )
 252        json_data = get_cfbd_player_recruit_ratings(
 253            season=2020,
 254            position="WR"
 255        )
 256        print(json_data)
 257        time.sleep(5)
 258
 259        # Get a list of all recruits from
 260        # the state of Idaho in the 2017 recruiting class.
 261        print(
 262            "Get a list of all recruits " +
 263            "from the state of Idaho in the 2017 recruiting class."
 264        )
 265        json_data = get_cfbd_player_recruit_ratings(
 266            season=2020,
 267            state="ID"
 268        )
 269        print(json_data)
 270        time.sleep(5)
 271
 272
 273        # You can also tell this function to just return the API call as
 274        # a Dictionary (read: JSON) object.
 275        print(
 276            "You can also tell this function to just return the API call " +
 277            "as a Dictionary (read: JSON) object."
 278        )
 279        json_data = get_cfbd_player_recruit_ratings(
 280            season=2020,
 281            team="Ohio",
 282            return_as_dict=True
 283        )
 284        print(json_data)
 285    ```
 286    Returns
 287    ----------
 288    A pandas `DataFrame` object with CFB team recruiting ratings,
 289    or (if `return_as_dict` is set to `True`)
 290    a dictionary object with CFB team recruiting ratings.
 291
 292    """
 293
 294    # now = datetime.now()
 295    recruit_df = pd.DataFrame()
 296    # row_df = pd.DataFrame()
 297    url = "https://api.collegefootballdata.com/recruiting/players"
 298
 299    ##########################################################################
 300
 301    if api_key is not None:
 302        real_api_key = api_key
 303        del api_key
 304    else:
 305        real_api_key = get_cfbd_api_token(api_key_dir=api_key_dir)
 306
 307    if real_api_key == "tigersAreAwesome":
 308        raise ValueError(
 309            "You actually need to change `cfbd_key` to your CFBD API key."
 310        )
 311    elif "Bearer " in real_api_key:
 312        pass
 313    elif "Bearer" in real_api_key:
 314        real_api_key = real_api_key.replace("Bearer", "Bearer ")
 315    else:
 316        real_api_key = "Bearer " + real_api_key
 317
 318    # if season > (now.year + 1):
 319    #     raise ValueError(f"`season` cannot be greater than {season}.")
 320    # elif season < 1869:
 321    #     raise ValueError("`season` cannot be less than 1869.")
 322
 323    if season < 1869:
 324        raise ValueError("`season` cannot be less than 1869.")
 325
 326    if (
 327        recruit_classification == "HighSchool"
 328        or recruit_classification == "JUCO"
 329        or recruit_classification == "PrepSchool"
 330    ):
 331        logging.info("Correct `recruit_classification` inputted.")
 332    elif recruit_classification is None:
 333        logging.info(
 334            "`recruit_classification` is skipped in this function call."
 335        )
 336    else:
 337        raise ValueError(
 338            "`recruit_classification` must be set "
 339            + "to one of the following values "
 340            + "\n\t- `HighSchool`"
 341            + "\n\t- `JUCO`"
 342            + "\n\t- `PrepSchool`"
 343        )
 344
 345    if season is None and team is None:
 346        raise ValueError(
 347            "`season` and/or `team` must be set to "
 348            + "valid non-null values for this function to work."
 349        )
 350
 351    # URL builder
 352    ##########################################################################
 353
 354    # Required by API
 355    if team is not None and season is None:
 356        url += f"?team={team}"
 357    elif season is not None and team is None:
 358        url += f"?year={season}"
 359    elif season is not None and team is not None:
 360        url += f"?year={season}&team={team}"
 361
 362    if recruit_classification is not None:
 363        url += f"&classification={recruit_classification}"
 364
 365    if position is not None:
 366        url += f"&position={position}"
 367
 368    if state is not None:
 369        url += f"&state={state}"
 370
 371    headers = {
 372        "Authorization": f"{real_api_key}",
 373        "accept": "application/json"
 374    }
 375    response = requests.get(url, headers=headers)
 376
 377    if response.status_code == 200:
 378        pass
 379    elif response.status_code == 401:
 380        raise ConnectionRefusedError(
 381            "Could not connect. The connection was refused." +
 382            "\nHTTP Status Code 401."
 383        )
 384    else:
 385        raise ConnectionError(
 386            f"Could not connect.\nHTTP Status code {response.status_code}"
 387        )
 388
 389    json_data = response.json()
 390
 391    if return_as_dict is True:
 392        return json_data
 393
 394    # for player in tqdm(json_data):
 395    #     pass
 396    recruit_df = pd.json_normalize(json_data)
 397
 398    recruit_df.rename(
 399        columns={
 400            "id": "recruit_id",
 401            "athleteId": "athlete_id",
 402            "recruitType": "recruit_type",
 403            "year": "season",
 404            "name": "player_name",
 405            "school": "previous_school",
 406            "committedTo": "college_commit_team",
 407            "stateProvince": "state_province",
 408            "hometownInfo.latitude": "hometown_latitude",
 409            "hometownInfo.longitude": "hometown_longitude",
 410            "hometownInfo.fipsCode": "hometown_fips_code",
 411        },
 412        inplace=True,
 413    )
 414
 415    return recruit_df
 416
 417
 418def get_cfbd_team_recruiting_ratings(
 419    api_key: str = None,
 420    api_key_dir: str = None,
 421    season: int = None,
 422    team: str = None,
 423    return_as_dict: bool = False,
 424):
 425    """
 426    Allows you to get CFB team recruiting rankings data from the CFBD API.
 427
 428    Parameters
 429    ----------
 430
 431    `api_key` (str, optional):
 432        Semi-optional argument.
 433        If `api_key` is null, this function will attempt to load a CFBD API key
 434        from the python environment, or from a file on this computer.
 435        If `api_key` is not null,
 436        this function will automatically assume that the
 437        inputted `api_key` is a valid CFBD API key.
 438
 439    `api_key_dir` (str, optional):
 440        Optional argument.
 441        If `api_key` is set to am empty string, this variable is ignored.
 442        If `api_key_dir` is null, and `api_key` is null,
 443        this function will try to find
 444        a CFBD API key file in this user's home directory.
 445        If `api_key_dir` is set to a string, and `api_key` is null,
 446        this function will assume that `api_key_dir` is a directory,
 447        and will try to find a CFBD API key file in that directory.
 448
 449    `season` (int, semi-mandatory):
 450        Semi-required argument.
 451        Specifies the season you want CFB recruiting data from.
 452        This must be specified, otherwise this package, and by extension
 453        the CFBD API, will not accept the request to get CFB recruiting data.
 454        This or `team` must be set to a valid non-null variable
 455        for this to function.
 456
 457    `team` (str, semi-mandatory):
 458        Semi-required argument.
 459        Specifies the season you want CFB recruiting data from.
 460        This must be specified, otherwise this package, and by extension
 461        the CFBD API, will not accept the request to get CFB recruiting data.
 462        This or `season` must be set to a valid non-null variable
 463        for this to function.
 464
 465    `return_as_dict` (bool, semi-optional):
 466        Semi-optional argument.
 467        If you want this function to return
 468        the data as a dictionary (read: JSON object),
 469        instead of a pandas `DataFrame` object,
 470        set `return_as_dict` to `True`.
 471
 472    Usage
 473    ----------
 474    ```
 475    import time
 476
 477    from cfbd_json_py.recruiting import get_cfbd_team_recruiting_ratings
 478
 479
 480    cfbd_key = "tigersAreAwesome"  # placeholder for your CFBD API Key.
 481
 482    if cfbd_key != "tigersAreAwesome":
 483        print(
 484            "Using the user's API key declared in this script " +
 485            "for this example."
 486        )
 487
 488        # Get a team recruiting rankings for the 2020 CFB season.
 489        print("Get a team recruiting rankings for the 2020 CFB season.")
 490        json_data = get_cfbd_team_recruiting_ratings(
 491            api_key=cfbd_key,
 492            season=2020
 493        )
 494        print(json_data)
 495        time.sleep(5)
 496
 497        # Get a historical team recruiting rankings for
 498        # the Ohio State Buckeyes Football team.
 499        print(
 500            "Get a historical team recruiting rankings for " +
 501            "the Ohio State Buckeyes Football team."
 502        )
 503        json_data = get_cfbd_team_recruiting_ratings(
 504            api_key=cfbd_key,
 505            team="Ohio State"
 506        )
 507        print(json_data)
 508        time.sleep(5)
 509
 510        # You can also tell this function to just return the API call as
 511        # a Dictionary (read: JSON) object.
 512        print(
 513            "You can also tell this function to just return the API call " +
 514            "as a Dictionary (read: JSON) object."
 515        )
 516        json_data = get_cfbd_team_recruiting_ratings(
 517            api_key=cfbd_key,
 518            season=2020,
 519            team="Ohio",
 520            return_as_dict=True
 521        )
 522        print(json_data)
 523
 524    else:
 525        # Alternatively, if the CFBD API key exists in this python environment,
 526        # or it's been set by cfbd_json_py.utls.set_cfbd_api_token(),
 527        # you could just call these functions directly,
 528        # without setting the API key in the script.
 529        print(
 530            "Using the user's API key supposedly loaded " +
 531            "into this python environment for this example."
 532        )
 533
 534
 535        # Get a team recruiting rankings for the 2020 CFB season.
 536        print("Get a team recruiting rankings for the 2020 CFB season.")
 537        json_data = get_cfbd_team_recruiting_ratings(
 538            season=2020
 539        )
 540        print(json_data)
 541        time.sleep(5)
 542
 543        # Get a historical team recruiting rankings for
 544        # the Ohio State Buckeyes Football team.
 545        print(
 546            "Get a historical team recruiting rankings for " +
 547            "the Ohio State Buckeyes Football team."
 548        )
 549        json_data = get_cfbd_team_recruiting_ratings(
 550            team="Ohio State"
 551        )
 552        print(json_data)
 553        time.sleep(5)
 554
 555        # You can also tell this function to just return the API call as
 556        # a Dictionary (read: JSON) object.
 557        print(
 558            "You can also tell this function to just return the API call " +
 559            "as a Dictionary (read: JSON) object."
 560        )
 561        json_data = get_cfbd_team_recruiting_ratings(
 562            season=2020,
 563            team="Ohio",
 564            return_as_dict=True
 565        )
 566        print(json_data)
 567
 568    ```
 569    Returns
 570    ----------
 571    A pandas `DataFrame` object with CFB Poll data,
 572    or (if `return_as_dict` is set to `True`)
 573    a dictionary object with CFB Poll data.
 574    """
 575
 576    # now = datetime.now()
 577    recruit_df = pd.DataFrame()
 578    # row_df = pd.DataFrame()
 579    url = "https://api.collegefootballdata.com/recruiting/teams"
 580
 581    ##########################################################################
 582
 583    if api_key is not None:
 584        real_api_key = api_key
 585        del api_key
 586    else:
 587        real_api_key = get_cfbd_api_token(api_key_dir=api_key_dir)
 588
 589    if real_api_key == "tigersAreAwesome":
 590        raise ValueError(
 591            "You actually need to change `cfbd_key` to your CFBD API key."
 592        )
 593    elif "Bearer " in real_api_key:
 594        pass
 595    elif "Bearer" in real_api_key:
 596        real_api_key = real_api_key.replace("Bearer", "Bearer ")
 597    else:
 598        real_api_key = "Bearer " + real_api_key
 599
 600    # if season > (now.year + 1):
 601    #     raise ValueError(f"`season` cannot be greater than {season}.")
 602    # elif season < 1869:
 603    #     raise ValueError("`season` cannot be less than 1869.")
 604
 605    if season < 1869:
 606        raise ValueError("`season` cannot be less than 1869.")
 607
 608    if season is None and team is None:
 609        raise ValueError(
 610            "`season` and/or `team` must be set to "
 611            + "valid non-null values for this function to work."
 612        )
 613
 614    # URL builder
 615    ##########################################################################
 616
 617    url_elements = 0
 618
 619    if season is not None and url_elements == 0:
 620        url += f"?year={season}"
 621        url_elements += 1
 622    elif season is not None:
 623        url += f"&year={season}"
 624        url_elements += 1
 625
 626    if team is not None and url_elements == 0:
 627        url += f"?team={team}"
 628        url_elements += 1
 629    elif team is not None:
 630        url += f"&team={team}"
 631        url_elements += 1
 632
 633    headers = {
 634        "Authorization": f"{real_api_key}",
 635        "accept": "application/json"
 636    }
 637    response = requests.get(url, headers=headers)
 638
 639    if response.status_code == 200:
 640        pass
 641    elif response.status_code == 401:
 642        raise ConnectionRefusedError(
 643            "Could not connect. The connection was refused." +
 644            "\nHTTP Status Code 401."
 645        )
 646    else:
 647        raise ConnectionError(
 648            f"Could not connect.\nHTTP Status code {response.status_code}"
 649        )
 650
 651    json_data = response.json()
 652
 653    if return_as_dict is True:
 654        return json_data
 655
 656    # for player in tqdm(json_data):
 657    #     pass
 658    recruit_df = pd.json_normalize(json_data)
 659
 660    return recruit_df
 661
 662
 663def get_cfbd_team_recruiting_group_ratings(
 664    api_key: str = None,
 665    api_key_dir: str = None,
 666    start_season: int = None,
 667    end_season: int = None,
 668    team: str = None,
 669    conference: str = None,
 670    return_as_dict: bool = False,
 671):
 672    """
 673    Allows you to get CFB player recruiting data,
 674    grouped by the team and position,
 675    from the CFBD API.
 676
 677    Parameters
 678    ----------
 679
 680    `api_key` (str, optional):
 681        Semi-optional argument.
 682        If `api_key` is null, this function will attempt to load a CFBD API key
 683        from the python environment, or from a file on this computer.
 684        If `api_key` is not null,
 685        this function will automatically assume that the
 686        inputted `api_key` is a valid CFBD API key.
 687
 688    `api_key_dir` (str, optional):
 689        Optional argument.
 690        If `api_key` is set to am empty string, this variable is ignored.
 691        If `api_key_dir` is null, and `api_key` is null,
 692        this function will try to find
 693        a CFBD API key file in this user's home directory.
 694        If `api_key_dir` is set to a string, and `api_key` is null,
 695        this function will assume that `api_key_dir` is a directory,
 696        and will try to find a CFBD API key file in that directory.
 697
 698    `start_season` (int, optional):
 699        Optional argument.
 700        If `start_season` is set to a valid integer,
 701        the API will filter out every recruiting season that
 702        is less than `start_season`.
 703
 704    `end_season` (int, optional):
 705        Optional argument.
 706        If `start_season` is set to a valid integer,
 707        the API will filter out every recruiting season that
 708        is greater than `end_season`.
 709
 710    `team` (str, semi-mandatory):
 711        Semi-required argument.
 712        Specifies the season you want CFB recruiting data from.
 713        This must be specified, otherwise this package, and by extension
 714        the CFBD API, will not accept the request to get CFB recruiting data.
 715        This or `season` must be set to a valid non-null variable
 716        for this to function.
 717
 718    `conference` (str, optional):
 719        Optional argument.
 720        If you only want CFB recruiting data
 721        from teams in a specific conference,
 722        set `conference` to the abbreviation
 723        of the conference you want CFB recruiting data from.
 724        For a list of conferences,
 725        use the `cfbd_json_py.conferences.get_cfbd_conference_info()`
 726        function.
 727
 728    `return_as_dict` (bool, semi-optional):
 729        Semi-optional argument.
 730        If you want this function to return
 731        the data as a dictionary (read: JSON object),
 732        instead of a pandas `DataFrame` object,
 733        set `return_as_dict` to `True`.
 734
 735    Usage
 736    ----------
 737    ```
 738    import time
 739
 740    from cfbd_json_py.recruiting import get_cfbd_team_recruiting_group_ratings
 741
 742
 743    cfbd_key = "tigersAreAwesome"  # placeholder for your CFBD API Key.
 744
 745    if cfbd_key != "tigersAreAwesome":
 746        print(
 747            "Using the user's API key declared in this script " +
 748            "for this example."
 749        )
 750
 751        # Get recruiting data between 2020 and 2023,
 752        # grouped by team and position.
 753        print(
 754            "Get recruiting data between 2020 and 2023, " +
 755            "grouped by team and position."
 756        )
 757        json_data = get_cfbd_team_recruiting_group_ratings(
 758            api_key=cfbd_key,
 759            start_season=2020,
 760            end_season=2023
 761        )
 762        print(json_data)
 763        time.sleep(5)
 764
 765        # Get recruiting data between 2020 and 2023,
 766        # grouped by team and position,
 767        # for the Ohio State Buckeyes Football team.
 768        print(
 769            "Get recruiting data between 2020 and 2023, " +
 770            "grouped by team and position, " +
 771            "for the Ohio State Buckeyes Football team."
 772        )
 773        json_data = get_cfbd_team_recruiting_group_ratings(
 774            api_key=cfbd_key,
 775            start_season=2020,
 776            end_season=2023,
 777            team="Ohio State"
 778        )
 779        print(json_data)
 780        time.sleep(5)
 781
 782        # Get recruiting data starting in 2020,
 783        # grouped by team and position.
 784        print(
 785            "Get recruiting data starting in 2020, " +
 786            "grouped by team and position."
 787        )
 788        json_data = get_cfbd_team_recruiting_group_ratings(
 789            api_key=cfbd_key,
 790            start_season=2020
 791        )
 792        print(json_data)
 793        time.sleep(5)
 794
 795        # Get recruiting data ending in 2018,
 796        # grouped by team and position.
 797        print(
 798            "Get recruiting data ending in 2018, grouped by team and position."
 799        )
 800        json_data = get_cfbd_team_recruiting_group_ratings(
 801            api_key=cfbd_key,
 802            start_season=2020
 803        )
 804        print(json_data)
 805        time.sleep(5)
 806
 807        # Get recruiting data starting in 2020,
 808        # grouped by team and position,
 809        # but only for Mountain West conference (MWC) teams.
 810        print(
 811            "Get recruiting data starting in 2020, " +
 812            "grouped by team and position, " +
 813            "but only for Mountain West conference (MWC) teams."
 814        )
 815        json_data = get_cfbd_team_recruiting_group_ratings(
 816            api_key=cfbd_key,
 817            start_season=2020,
 818            conference="MWC"
 819        )
 820        print(json_data)
 821        time.sleep(5)
 822
 823        # You can also tell this function to just return the API call as
 824        # a Dictionary (read: JSON) object.
 825        print(
 826            "You can also tell this function to just return the API call " +
 827            "as a Dictionary (read: JSON) object."
 828        )
 829        json_data = get_cfbd_team_recruiting_group_ratings(
 830            api_key=cfbd_key,
 831            start_season=2020,
 832            end_season=2023,
 833            team="Ohio",
 834            return_as_dict=True
 835        )
 836        print(json_data)
 837
 838    else:
 839        # Alternatively, if the CFBD API key exists in this python environment,
 840        # or it's been set by cfbd_json_py.utls.set_cfbd_api_token(),
 841        # you could just call these functions directly,
 842        # without setting the API key in the script.
 843        print(
 844            "Using the user's API key supposedly loaded " +
 845            "into this python environment for this example."
 846        )
 847
 848
 849        # Get recruiting data between 2020 and 2023,
 850        # grouped by team and position.
 851        print(
 852            "Get recruiting data between 2020 and 2023, " +
 853            "grouped by team and position."
 854        )
 855        json_data = get_cfbd_team_recruiting_group_ratings(
 856            start_season=2020,
 857            end_season=2023
 858        )
 859        print(json_data)
 860        time.sleep(5)
 861
 862        # Get recruiting data between 2020 and 2023,
 863        # grouped by team and position,
 864        # for the Ohio State Buckeyes Football team.
 865        print(
 866            "Get recruiting data between 2020 and 2023, " +
 867            "grouped by team and position, " +
 868            "for the Ohio State Buckeyes Football team."
 869        )
 870        json_data = get_cfbd_team_recruiting_group_ratings(
 871            start_season=2020,
 872            end_season=2023,
 873            team="Ohio State"
 874        )
 875        print(json_data)
 876        time.sleep(5)
 877
 878        # Get recruiting data starting in 2020,
 879        # grouped by team and position.
 880        print(
 881            "Get recruiting data starting in 2020, " +
 882            "grouped by team and position."
 883        )
 884        json_data = get_cfbd_team_recruiting_group_ratings(
 885            start_season=2020
 886        )
 887        print(json_data)
 888        time.sleep(5)
 889
 890        # Get recruiting data ending in 2018,
 891        # grouped by team and position.
 892        print(
 893            "Get recruiting data ending in 2018, grouped by team and position."
 894        )
 895        json_data = get_cfbd_team_recruiting_group_ratings(
 896            end_season=2018
 897        )
 898        print(json_data)
 899        time.sleep(5)
 900
 901        # Get recruiting data starting in 2020,
 902        # grouped by team and position,
 903        # but only for Mountain West conference (MWC) teams.
 904        print(
 905            "Get recruiting data starting in 2020, " +
 906            "grouped by team and position, " +
 907            "but only for Mountain West conference (MWC) teams."
 908        )
 909        json_data = get_cfbd_team_recruiting_group_ratings(
 910            start_season=2020,
 911            conference="MWC"
 912        )
 913        print(json_data)
 914        time.sleep(5)
 915
 916        # You can also tell this function to just return the API call as
 917        # a Dictionary (read: JSON) object.
 918        print(
 919            "You can also tell this function to just return the API call " +
 920            "as a Dictionary (read: JSON) object."
 921        )
 922        json_data = get_cfbd_team_recruiting_group_ratings(
 923            start_season=2020,
 924            end_season=2023,
 925            team="Ohio",
 926            return_as_dict=True
 927        )
 928        print(json_data)
 929    ```
 930    Returns
 931    ----------
 932    A pandas `DataFrame` object with CFB team recruiting ratings,
 933    or (if `return_as_dict` is set to `True`)
 934    a dictionary object with CFB team recruiting ratings.
 935    """
 936    now = datetime.now()
 937    recruit_df = pd.DataFrame()
 938    # row_df = pd.DataFrame()
 939    url = "https://api.collegefootballdata.com/recruiting/groups"
 940
 941    ##########################################################################
 942
 943    if api_key is not None:
 944        real_api_key = api_key
 945        del api_key
 946    else:
 947        real_api_key = get_cfbd_api_token(api_key_dir=api_key_dir)
 948
 949    if real_api_key == "tigersAreAwesome":
 950        raise ValueError(
 951            "You actually need to change `cfbd_key` to your CFBD API key."
 952        )
 953    elif "Bearer " in real_api_key:
 954        pass
 955    elif "Bearer" in real_api_key:
 956        real_api_key = real_api_key.replace("Bearer", "Bearer ")
 957    else:
 958        real_api_key = "Bearer " + real_api_key
 959
 960    if start_season is not None and start_season > (now.year + 1):
 961        raise ValueError(f"`season` cannot be greater than {start_season}.")
 962    elif start_season is not None and start_season < 1869:
 963        raise ValueError("`season` cannot be less than 1869.")
 964
 965    if end_season is not None and end_season > (now.year + 1):
 966        raise ValueError(f"`season` cannot be greater than {end_season}.")
 967    elif end_season is not None and end_season < 1869:
 968        raise ValueError("`season` cannot be less than 1869.")
 969
 970    # URL builder
 971    ##########################################################################
 972
 973    url_elements = 0
 974
 975    if start_season is not None and url_elements == 0:
 976        url += f"?startYear={start_season}"
 977        url_elements += 1
 978    elif start_season is not None:
 979        url += f"&startYear={start_season}"
 980        url_elements += 1
 981
 982    if end_season is not None and url_elements == 0:
 983        url += f"?endYear={end_season}"
 984        url_elements += 1
 985    elif end_season is not None:
 986        url += f"&endYear={end_season}"
 987        url_elements += 1
 988
 989    if team is not None and url_elements == 0:
 990        url += f"?team={team}"
 991        url_elements += 1
 992    elif team is not None:
 993        url += f"&team={team}"
 994        url_elements += 1
 995
 996    if conference is not None and url_elements == 0:
 997        url += f"?conference={conference}"
 998        url_elements += 1
 999    elif conference is not None:
1000        url += f"&conference={conference}"
1001        url_elements += 1
1002
1003    headers = {
1004        "Authorization": f"{real_api_key}",
1005        "accept": "application/json"
1006    }
1007    response = requests.get(url, headers=headers)
1008
1009    if response.status_code == 200:
1010        pass
1011    elif response.status_code == 401:
1012        raise ConnectionRefusedError(
1013            "Could not connect. The connection was refused." +
1014            "\nHTTP Status Code 401."
1015        )
1016    else:
1017        raise ConnectionError(
1018            f"Could not connect.\nHTTP Status code {response.status_code}"
1019        )
1020
1021    json_data = response.json()
1022
1023    if return_as_dict is True:
1024        return json_data
1025
1026    # for player in tqdm(json_data):
1027    #     pass
1028    recruit_df = pd.json_normalize(json_data)
1029
1030    return recruit_df