cfbd_json_py.draft

  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: draft.py
  5# Purpose: Houses functions pertaining to NFL Draft data within the CFBD API.
  6###############################################################################
  7
  8import logging
  9from datetime import datetime
 10
 11import pandas as pd
 12import requests
 13
 14# from tqdm import tqdm
 15from cfbd_json_py.utls import get_cfbd_api_token
 16
 17
 18def get_cfbd_nfl_teams(
 19    api_key: str = None, api_key_dir: str = None, return_as_dict: bool = False
 20):
 21    """
 22    Retrieves a list of NFL teams from the CFBD API.
 23
 24    Parameters
 25    ----------
 26    `api_key` (str, optional):
 27        Semi-optional argument.
 28        If `api_key` is null, this function will attempt to load a CFBD API key
 29        from the python environment, or from a file on this computer.
 30        If `api_key` is not null,
 31        this function will automatically assume that the
 32        inputted `api_key` is a valid CFBD API key.
 33
 34    `api_key_dir` (str, optional):
 35        Optional argument.
 36        If `api_key` is set to am empty string, this variable is ignored.
 37        If `api_key_dir` is null, and `api_key` is null,
 38        this function will try to find
 39        a CFBD API key file in this user's home directory.
 40        If `api_key_dir` is set to a string, and `api_key` is null,
 41        this function will assume that `api_key_dir` is a directory,
 42        and will try to find a CFBD API key file in that directory.
 43
 44    `return_as_dict` (bool, semi-optional):
 45        Semi-optional argument.
 46        If you want this function to return the data
 47        as a dictionary (read: JSON object),
 48        instead of a pandas `DataFrame` object,
 49        set `return_as_dict` to `True`.
 50
 51    Usage
 52    ----------
 53    ```
 54    import time
 55
 56    from cfbd_json_py.draft import get_cfbd_nfl_teams
 57
 58    cfbd_key = "tigersAreAwesome"  # placeholder for your CFBD API Key.
 59
 60    if cfbd_key is not "tigersAreAwesome":
 61        print(
 62            "Using the user's API key declared in this script " +
 63            "for this example."
 64        )
 65
 66        # Gets NFL team info from the CFBD API.
 67        print("Gets NFL team info from the CFBD API.")
 68        json_data = get_cfbd_nfl_teams(api_key=cfbd_key)
 69        print(json_data)
 70        time.sleep(5)
 71
 72        # You can also tell this function to just return the API call
 73        # as a Dictionary (read: JSON) object.
 74        print(
 75            "You can also tell this function to just return the API call " +
 76            "as a Dictionary (read: JSON) object."
 77        )
 78        json_data = get_cfbd_nfl_teams(
 79            api_key=cfbd_key,
 80            return_as_dict=True)
 81        print(json_data)
 82
 83    else:
 84        # Alternatively, if the CFBD API key exists in this python environment,
 85        # or it's been set by cfbd_json_py.utls.set_cfbd_api_token(),
 86        # you could just call these functions directly,
 87        # without setting the API key in the script.
 88        print(
 89            "Using the user's API key supposedly loaded into " +
 90            "this python environment for this example."
 91        )
 92
 93        # Gets NFL team info from the CFBD API.
 94        print("Gets NFL team info from the CFBD API.")
 95        json_data = get_cfbd_nfl_teams()
 96        print(json_data)
 97        time.sleep(5)
 98
 99        # You can also tell this function to just return the API call
100        # as a Dictionary (read: JSON) object.
101        print(
102            "You can also tell this function to just return the API call " +
103            "as a Dictionary (read: JSON) object."
104        )
105        json_data = get_cfbd_nfl_teams(return_as_dict=True)
106        print(json_data)
107
108    ```
109
110    Returns
111    ----------
112    A pandas `DataFrame` object with NFL team data,
113    or (if `return_as_dict` is set to `True`)
114    a dictionary object with NFL team data.
115
116    """
117
118    nfl_teams_df = pd.DataFrame()
119    # row_df = pd.DataFrame()
120    url = "https://api.collegefootballdata.com/draft/teams"
121
122    # Input validation
123    ##########################################################################
124
125    if api_key is not None:
126        real_api_key = api_key
127        del api_key
128    else:
129        real_api_key = get_cfbd_api_token(api_key_dir=api_key_dir)
130
131    if real_api_key == "tigersAreAwesome":
132        raise ValueError(
133            "You actually need to change `cfbd_key` to your CFBD API key."
134        )
135    elif "Bearer " in real_api_key:
136        pass
137    elif "Bearer" in real_api_key:
138        real_api_key = real_api_key.replace("Bearer", "Bearer ")
139    else:
140        real_api_key = "Bearer " + real_api_key
141
142    headers = {
143        "Authorization": f"{real_api_key}",
144        "accept": "application/json"
145    }
146
147    response = requests.get(url, headers=headers)
148
149    if response.status_code == 200:
150        pass
151    elif response.status_code == 401:
152        raise ConnectionRefusedError(
153            "Could not connect. The connection was refused.\n" +
154            "HTTP Status Code 401."
155        )
156    else:
157        raise ConnectionError(
158            f"Could not connect.\nHTTP Status code {response.status_code}"
159        )
160
161    json_data = response.json()
162
163    if return_as_dict is True:
164        return json_data
165
166    nfl_teams_df = pd.json_normalize(json_data)
167    nfl_teams_df.rename(columns={"displayName": "display_name"}, inplace=True)
168    return nfl_teams_df
169
170
171def get_cfbd_nfl_positions(
172    api_key: str = None, api_key_dir: str = None, return_as_dict: bool = False
173):
174    """
175    Retrieves a list of player positions for the NFL Draft from the CFBD API.
176
177    Parameters
178    ----------
179    `api_key` (str, optional):
180        Semi-optional argument.
181        If `api_key` is null, this function will attempt to load a CFBD API key
182        from the python environment, or from a file on this computer.
183        If `api_key` is not null,
184        this function will automatically assume that the
185        inputted `api_key` is a valid CFBD API key.
186
187    `api_key_dir` (str, optional):
188        Optional argument.
189        If `api_key` is set to am empty string, this variable is ignored.
190        If `api_key_dir` is null, and `api_key` is null,
191        this function will try to find
192        a CFBD API key file in this user's home directory.
193        If `api_key_dir` is set to a string, and `api_key` is null,
194        this function will assume that `api_key_dir` is a directory,
195        and will try to find a CFBD API key file in that directory.
196
197    `return_as_dict` (bool, semi-optional):
198        Semi-optional argument.
199        If you want this function to return
200        the data as a dictionary (read: JSON object),
201        instead of a pandas `DataFrame` object,
202        set `return_as_dict` to `True`.
203
204    Usage
205    ----------
206    ```
207    import time
208
209    from cfbd_json_py.draft import get_cfbd_nfl_positions
210
211    cfbd_key = "tigersAreAwesome"  # placeholder for your CFBD API Key.
212
213    if cfbd_key is not "tigersAreAwesome":
214        print(
215            "Using the user's API key declared in this script " +
216            "for this example."
217        )
218
219        # Gets a list of player positions for the NFL Draft from the CFBD API.
220        print(
221            "Gets a list of player positions for the NFL Draft " +
222            "from the CFBD API."
223        )
224        json_data = get_cfbd_nfl_positions(api_key=cfbd_key)
225        print(json_data)
226        time.sleep(5)
227
228        # You can also tell this function to just return the API call
229        # as a Dictionary (read: JSON) object.
230        print(
231            "You can also tell this function to just return the API call " +
232            "as a Dictionary (read: JSON) object."
233        )
234        json_data = get_cfbd_nfl_positions(
235            api_key=cfbd_key,
236            return_as_dict=True)
237        print(json_data)
238
239    else:
240        # Alternatively, if the CFBD API key exists in this python environment,
241        # or it's been set by cfbd_json_py.utls.set_cfbd_api_token(),
242        # you could just call these functions directly,
243        # without setting the API key in the script.
244        print(
245            "Using the user's API key supposedly loaded into " +
246            "this python environment for this example."
247        )
248
249        # Gets a list of player positions for the NFL Draft from the CFBD API.
250        print(
251            "Gets a list of player positions for the NFL Draft " +
252            "from the CFBD API."
253        )
254        json_data = get_cfbd_nfl_positions()
255        print(json_data)
256        time.sleep(5)
257
258        # You can also tell this function to just return the API call
259        # as a Dictionary (read: JSON) object.
260        print(
261            "You can also tell this function to just return the API call " +
262            "as a Dictionary (read: JSON) object."
263        )
264        json_data = get_cfbd_nfl_positions(return_as_dict=True)
265        print(json_data)
266
267    ```
268    Returns
269    ----------
270    A pandas `DataFrame` object with player position data,
271    or (if `return_as_dict` is set to `True`)
272    a dictionary object with player position data.
273
274    """
275
276    positions_df = pd.DataFrame()
277    # row_df = pd.DataFrame()
278    url = "https://api.collegefootballdata.com/draft/positions"
279
280    # Input validation
281    ##########################################################################
282
283    if api_key is not None:
284        real_api_key = api_key
285        del api_key
286    else:
287        real_api_key = get_cfbd_api_token(api_key_dir=api_key_dir)
288
289    if real_api_key == "tigersAreAwesome":
290        raise ValueError(
291            "You actually need to change `cfbd_key` to your CFBD API key."
292        )
293    elif "Bearer " in real_api_key:
294        pass
295    elif "Bearer" in real_api_key:
296        real_api_key = real_api_key.replace("Bearer", "Bearer ")
297    else:
298        real_api_key = "Bearer " + real_api_key
299
300    headers = {
301        "Authorization": f"{real_api_key}",
302        "accept": "application/json"
303    }
304
305    response = requests.get(url, headers=headers)
306
307    if response.status_code == 200:
308        pass
309    elif response.status_code == 401:
310        raise ConnectionRefusedError(
311            "Could not connect. The connection was refused.\n" +
312            "HTTP Status Code 401."
313        )
314    else:
315        raise ConnectionError(
316            f"Could not connect.\nHTTP Status code {response.status_code}"
317        )
318
319    json_data = response.json()
320
321    if return_as_dict is True:
322        return json_data
323
324    # for p in json_data:
325    #     position_name = p['name']
326    #     position_abbreviation = p['abbreviation']
327
328    #     row_df = pd.DataFrame(
329    #         {
330    #             "position_name": position_name,
331    #             "position_abbreviation": position_abbreviation
332    #         }, index=[0]
333    #     )
334    #     positions_df = pd.concat([positions_df, row_df], ignore_index=True)
335
336    #     del position_name, position_abbreviation
337    #     del row_df
338    positions_df = pd.json_normalize(json_data)
339    positions_df.rename(
340        columns={
341            "name": "position_name",
342            "abbreviation": "position_abbreviation",
343        },
344        inplace=True,
345    )
346
347    return positions_df
348
349
350def get_cfbd_nfl_draft_info(
351    api_key: str = None,
352    api_key_dir: str = None,
353    season: int = None,
354    nfl_team: str = None,
355    college: str = None,
356    conference: str = None,
357    position: str = None,
358    year: int = None,
359    return_as_dict: bool = False,
360):
361    """
362    Retrieves a list of actual NFL Draft selections from the CFBD API.
363
364    Parameters
365    ----------
366
367    `api_key` (str, optional):
368        Semi-optional argument.
369        If `api_key` is null, this function will attempt to load a CFBD API key
370        from the python environment, or from a file on this computer.
371        If `api_key` is not null,
372        this function will automatically assume that the
373        inputted `api_key` is a valid CFBD API key.
374
375    `api_key_dir` (str, optional):
376        Optional argument.
377        If `api_key` is set to am empty string, this variable is ignored.
378        If `api_key_dir` is null, and `api_key` is null,
379        this function will try to find
380        a CFBD API key file in this user's home directory.
381        If `api_key_dir` is set to a string, and `api_key` is null,
382        this function will assume that `api_key_dir` is a directory,
383        and will try to find a CFBD API key file in that directory.
384
385    The following parameters are optional,
386    but it is highly recommended to not call this function
387    without declaring one of these five optional parameters
388    as a non-null value.
389
390    `season` (int, semi-optional):
391        Semi-Optional argument.
392        This is the season you want NFL Draft information for.
393        For example, if you only want data for the 2020 NFL Draft,
394        set `season` to `2020`.
395
396    `nfl_team` (str, optional):
397        Semi-Optional argument.
398        If you only want NFL Draft selections from a specific NFL team,
399        set `nfl_team` to the name of that team.
400        For example, if you want to only get NFL Draft information for
401        draft picks made by the Cincinnati Bengals,
402        set `nfl_team` to `Cincinnati`.
403
404    `college` (str, optional):
405        Semi-Optional argument.
406        If you only want NFL Draft selections from a specific CFB team,
407        set `college` to the name of that team.
408        For example, if you want to only get NFL Draft information for
409        draft picks from the Clemson Tigers Football Program,
410        set `college` to `Clemson`.
411
412    `conference` (str, optional):
413        Semi-Optional argument.
414        If you only want NFL Draft selections from a specific CFB conference,
415        set `conference` to the abbreviation of that conference.
416        A list of CFBD API conference abbreviations can be found
417        in the `conference_abbreviation` column from
418        the pandas DataFrame that is returned by calling
419        `cfbd_json_py.conferences.get_cfbd_conference_info()`.
420        For example, if you want to only get NFL Draft information for
421        draft picks that played in the Big 12, set `conference` to `B12`.
422
423    `year` (int):
424        Alternative keyword for `season`
425
426    `position` (str, optional):
427        Semi-Optional argument.
428        If you only want NFL Draft selections who played a specific position,
429        set `position` to that position's abbreviation.
430        A list of CFBD API positions can be found in the
431        `position_abbreviation` column from
432        the pandas DataFrame that is returned by calling
433        `cfbd_json_py.draft.get_cfbd_nfl_positions()`.
434
435    `return_as_dict` (bool, semi-optional):
436        Semi-optional argument.
437        If you want this function to return the data
438        as a dictionary (read: JSON object),
439        instead of a pandas `DataFrame` object,
440        set `return_as_dict` to `True`.
441    Usage
442    ----------
443
444    ```
445    import time
446
447    from cfbd_json_py.draft import get_cfbd_nfl_draft_info
448
449    cfbd_key = "tigersAreAwesome"  # placeholder for your CFBD API Key.
450
451    if cfbd_key is not "tigersAreAwesome":
452        print(
453            "Using the user's API key declared in this script " +
454            "for this example."
455        )
456
457        # Get NFL Draft selections from the 2020 NFL Draft.
458        print("Get NFL Draft selections from the 2020 NFL Draft.")
459        json_data = get_cfbd_nfl_draft_info(
460            api_key=cfbd_key,
461            season=2020
462        )
463        print(json_data)
464        time.sleep(5)
465
466        # Get NFL Draft selections from the 2020 NFL Draft made by the
467        # 2020 Cincinnati Bengals.
468        print(
469            "Get NFL Draft selections from the 2020 NFL Draft made " +
470            "by the 2020 Cincinnati Bengals."
471        )
472        json_data = get_cfbd_nfl_draft_info(
473            api_key=cfbd_key,
474            season=2020,
475            nfl_team="Cincinnati"
476        )
477        print(json_data)
478        time.sleep(5)
479
480        # Get NFL Draft selections from the 2020 NFL Draft made involving
481        # Clemson Tigers football players.
482        print(
483            "Get NFL Draft selections from the 2020 NFL Draft made " +
484            "involving Clemson Tigers football players."
485        )
486        json_data = get_cfbd_nfl_draft_info(
487            api_key=cfbd_key,
488            season=2020,
489            college="Clemson"
490        )
491        print(json_data)
492        time.sleep(5)
493
494        # Get NFL Draft selections from the 2020 NFL Draft made involving
495        # players who played in the Southeastern conference (SEC).
496        print(
497            "Get NFL Draft selections from the 2020 NFL Draft made " +
498            "involving players who played " +
499            "in the Southeastern conference (SEC)."
500        )
501        json_data = get_cfbd_nfl_draft_info(
502            api_key=cfbd_key,
503            season=2020,
504            conference="SEC"
505        )
506        print(json_data)
507        time.sleep(5)
508
509        # Get NFL Draft selections from the 2020 NFL Draft made
510        # where the selected player was a QB in college.
511        print(
512            "Get NFL Draft selections from the 2020 NFL Draft made " +
513            "where the selected player was a QB in college."
514        )
515        json_data = get_cfbd_nfl_draft_info(
516            api_key=cfbd_key,
517            season=2020,
518            position="QB"
519        )
520        print(json_data)
521        time.sleep(5)
522
523        # You can also tell this function to just return the API call
524        # as a Dictionary (read: JSON) object.
525        print(
526            "You can also tell this function to just return the API call " +
527            "as a Dictionary (read: JSON) object."
528        )
529        json_data = get_cfbd_nfl_draft_info(
530            season=2020,
531            position="QB",
532            api_key=cfbd_key,
533            return_as_dict=True
534        )
535        print(json_data)
536
537    else:
538        # Alternatively, if the CFBD API key exists in this python environment,
539        # or it's been set by cfbd_json_py.utls.set_cfbd_api_token(),
540        # you could just call these functions directly,
541        # without setting the API key in the script.
542        print(
543            "Using the user's API key supposedly loaded " +
544            "into this python environment for this example."
545        )
546
547        # Get NFL Draft selections from the 2020 NFL Draft.
548        print("Get NFL Draft selections from the 2020 NFL Draft.")
549        json_data = get_cfbd_nfl_draft_info(season=2020)
550        print(json_data)
551        time.sleep(5)
552
553        # Get NFL Draft selections from the 2020 NFL Draft made by the
554        # 2020 Cincinnati Bengals.
555        print(
556            "Get NFL Draft selections from the 2020 NFL Draft " +
557            "made by the 2020 Cincinnati Bengals."
558        )
559        json_data = get_cfbd_nfl_draft_info(
560            season=2020,
561            nfl_team="Cincinnati"
562        )
563        print(json_data)
564        time.sleep(5)
565
566        # Get NFL Draft selections from the 2020 NFL Draft made involving
567        # Clemson Tigers football players.
568        print(
569            "Get NFL Draft selections from the 2020 NFL Draft made " +
570            "involving Clemson Tigers football players."
571        )
572        json_data = get_cfbd_nfl_draft_info(
573            season=2020,
574            college="Clemson"
575        )
576        print(json_data)
577        time.sleep(5)
578
579        # Get NFL Draft selections from the 2020 NFL Draft made involving
580        # players who played in the Southeastern conference (SEC).
581        print(
582            "Get NFL Draft selections from the 2020 NFL Draft made " +
583            "involving players who played " +
584            "in the Southeastern conference (SEC)."
585        )
586        json_data = get_cfbd_nfl_draft_info(
587            season=2020,
588            conference="SEC"
589        )
590        print(json_data)
591        time.sleep(5)
592
593        # Get NFL Draft selections from the 2020 NFL Draft made
594        # where the selected player was a QB in college.
595        print(
596            "Get NFL Draft selections from the 2020 NFL Draft made " +
597            "where the selected player was a QB in college."
598        )
599        json_data = get_cfbd_nfl_draft_info(
600            season=2020,
601            position="QB"
602        )
603        print(json_data)
604        time.sleep(5)
605
606        # You can also tell this function to just return the API call
607        # as a Dictionary (read: JSON) object.
608        print(
609            "You can also tell this function to just return the API call " +
610            "as a Dictionary (read: JSON) object."
611        )
612        json_data = get_cfbd_nfl_draft_info(
613            season=2020,
614            position="QB",
615            return_as_dict=True
616        )
617        print(json_data)
618
619    ```
620
621    Returns
622    ----------
623    A pandas `DataFrame` object with NFL Draft selection data,
624    or (if `return_as_dict` is set to `True`)
625    a dictionary object with NFL Draft selection data.
626
627    """
628    now = datetime.now()
629    nfl_draft_df = pd.DataFrame()
630    # row_df = pd.DataFrame()
631    url = "https://api.collegefootballdata.com/draft/picks"
632
633    # Input validation
634    ##########################################################################
635
636    # `year` to `season`
637    if season is not None and year is not None and (year is not season):
638        raise ValueError(
639            "When using this function, "
640            + "please specify a season in EITHER `year` or `season`."
641        )
642    if season is not None:
643        pass
644    elif year is not None:
645        season = year
646    else:
647        raise ValueError("No year/season inputted for this function.")
648
649    if api_key is not None:
650        real_api_key = api_key
651        del api_key
652    else:
653        real_api_key = get_cfbd_api_token(api_key_dir=api_key_dir)
654
655    if real_api_key == "tigersAreAwesome":
656        raise ValueError(
657            "You actually need to change `cfbd_key` to your CFBD API key."
658        )
659    elif "Bearer " in real_api_key:
660        pass
661    elif "Bearer" in real_api_key:
662        real_api_key = real_api_key.replace("Bearer", "Bearer ")
663    else:
664        real_api_key = "Bearer " + real_api_key
665
666    if season is None \
667            and nfl_team is None \
668            and college is None \
669            and conference is None:
670
671        logging.warning(
672            "Not specifying a `season`, `nfl_team`, `college`, "
673            + "or `conference` will still result in "
674            + "a successful get request (assuming the API key is valid)"
675            + ", but this is not a recommended method "
676            + "of calling this function."
677        )
678
679    if season < 1936 or season > now.year:
680        raise ValueError(
681            f"`season` must be an integer between 1936 and {now.year}.\n" +
682            f"You entered:\n{season}"
683        )
684
685    # URL builder
686    ##########################################################################
687
688    url_elements = 0
689
690    if season is not None and url_elements == 0:
691        url += f"?year={season}"
692        url_elements += 1
693    elif season is not None:
694        url += f"&year={season}"
695        url_elements += 1
696
697    if nfl_team is not None and url_elements == 0:
698        url += f"?nflTeam={nfl_team}"  # nfl_team = "Cincinnati", not "CIN"
699        url_elements += 1
700    elif nfl_team is not None:
701        url += f"&nflTeam={nfl_team}"
702        url_elements += 1
703
704    if college is not None and url_elements == 0:
705        url += f"?college={college}"
706        url_elements += 1
707    elif college is not None:
708        url += f"&college={college}"
709        url_elements += 1
710
711    if conference is not None and url_elements == 0:
712        # conference = "SEC", not "Southeastern conference"
713        url += f"?conference={conference}"
714        url_elements += 1
715    elif conference is not None:
716        url += f"&conference={conference}"
717        url_elements += 1
718
719    if position is not None and url_elements == 0:
720        url += f"?position={position}"
721        url_elements += 1
722    elif position is not None:
723        url += f"&position={position}"
724        url_elements += 1
725
726    headers = {
727        "Authorization": f"{real_api_key}",
728        "accept": "application/json"
729    }
730
731    response = requests.get(url, headers=headers)
732
733    if response.status_code == 200:
734        pass
735    elif response.status_code == 401:
736        raise ConnectionRefusedError(
737            "Could not connect. The connection was refused.\n" +
738            "HTTP Status Code 401."
739        )
740    else:
741        raise ConnectionError(
742            f"Could not connect.\nHTTP Status code {response.status_code}"
743        )
744
745    json_data = response.json()
746
747    if return_as_dict is True:
748        return json_data
749
750    nfl_draft_df = pd.json_normalize(json_data)
751    # print(nfl_draft_df.columns)
752    nfl_draft_df.rename(
753        columns={
754            "collegeAthleteId": "college_athlete_id",
755            "nflAthleteId": "nfl_athlete_id",
756            "collegeId": "college_id",
757            "collegeTeam": "college_team_name",
758            "collegeConference": "college_conference_name",
759            "preDraftRanking": "pre_draft_ranking",
760            "preDraftPositionRanking": "pre_draft_position_ranking",
761            "preDraftGrade": "pre_draft_grade",
762            "hometownInfo.city": "player_hometown_city",
763            "hometownInfo.state": "player_hometown_state",
764            "hometownInfo.country": "player_hometown_country",
765            "hometownInfo.latitude": "player_hometown_latitude",
766            "hometownInfo.longitude": "player_hometown_longitude",
767            "hometownInfo.countyFips": "player_hometown_county_fips",
768        },
769        inplace=True,
770    )
771    if len(nfl_draft_df) == 0:
772        logging.error(
773            "The CFBD API accepted your inputs, "
774            + "but found no data within your specified input parameters."
775            + " Please double check your input parameters."
776        )
777
778    return nfl_draft_df