cfbd_json_py.rankings

  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: rankings.py
  5# Purpose: Houses functions pertaining to CFB poll data within the CFBD API.
  6###############################################################################
  7
  8from datetime import datetime
  9
 10import pandas as pd
 11import requests
 12# from tqdm import tqdm
 13
 14from cfbd_json_py.utls import get_cfbd_api_token
 15
 16
 17def get_cfbd_poll_rankings(
 18    season: int,
 19    api_key: str = None,
 20    api_key_dir: str = None,
 21    week: int = None,
 22    season_type: str = "regular",  # "regular" or "postseason"
 23    return_as_dict: bool = False,
 24):
 25    """
 26    Allows you to get CFB poll rankings data from the CFBD API.
 27
 28    Parameters
 29    ----------
 30    `season` (int, mandatory):
 31        Required argument.
 32        Specifies the season you want CFB poll rankings data from.
 33        This must be specified, otherwise this package, and by extension
 34        the CFBD API, will not accept
 35        the request to get CFB poll rankings data.
 36
 37    `api_key` (str, optional):
 38        Semi-optional argument.
 39        If `api_key` is null, this function will attempt to load a CFBD API key
 40        from the python environment, or from a file on this computer.
 41        If `api_key` is not null,
 42        this function will automatically assume that the
 43        inputted `api_key` is a valid CFBD API key.
 44
 45    `api_key_dir` (str, optional):
 46        Optional argument.
 47        If `api_key` is set to am empty string, this variable is ignored.
 48        If `api_key_dir` is null, and `api_key` is null,
 49        this function will try to find
 50        a CFBD API key file in this user's home directory.
 51        If `api_key_dir` is set to a string, and `api_key` is null,
 52        this function will assume that `api_key_dir` is a directory,
 53        and will try to find a CFBD API key file in that directory.
 54
 55    `week` (int, optional):
 56        Optional argument.
 57        If `week` is set to an integer, this function will attempt
 58        to load CFB poll rankings data from games in that season,
 59        and in that week.
 60
 61    `season_type` (str, semi-optional):
 62        Semi-optional argument.
 63        By default, this will be set to "regular", for the CFB regular season.
 64        If you want CFB poll rankings data for non-regular season games,
 65        set `season_type` to "postseason".
 66        If `season_type` is set to anything but "regular" or "postseason",
 67        a `ValueError()` will be raised.
 68
 69    `return_as_dict` (bool, semi-optional):
 70        Semi-optional argument.
 71        If you want this function to return the data
 72        as a dictionary (read: JSON object),
 73        instead of a pandas `DataFrame` object,
 74        set `return_as_dict` to `True`.
 75
 76    Usage
 77    ----------
 78    ```
 79    import time
 80
 81    from cfbd_json_py.rankings import get_cfbd_poll_rankings
 82
 83
 84    cfbd_key = "tigersAreAwesome"  # placeholder for your CFBD API Key.
 85
 86    if cfbd_key != "tigersAreAwesome":
 87        print(
 88            "Using the user's API key declared in this " +
 89            "script for this example."
 90        )
 91
 92        # Get CFB poll data for the 2020 CFB season.
 93        print("Get CFB poll data for the 2020 CFB season.")
 94        json_data = get_cfbd_poll_rankings(
 95            api_key=cfbd_key,
 96            season=2020
 97        )
 98        print(json_data)
 99        time.sleep(5)
100
101        # Get CFB poll data from week 10 of the 2023 CFB season.
102        print("Get CFB poll data from week 10 of the 2023 CFB season.")
103        json_data = get_cfbd_poll_rankings(
104            api_key=cfbd_key,
105            season=2023,
106            week=10
107        )
108        print(json_data)
109        time.sleep(5)
110
111        # Get CFB poll data for the 2021 CFB season, during the postseason.
112        print(
113            "Get CFB poll data for the 2021 CFB season, during the postseason."
114        )
115        json_data = get_cfbd_poll_rankings(
116            api_key=cfbd_key,
117            season=2021,
118            season_type="postseason"
119        )
120        print(json_data)
121        time.sleep(5)
122
123        # You can also tell this function to just return the API call as
124        # a Dictionary (read: JSON) object.
125        print(
126            "You can also tell this function to just return the API call " +
127            "as a dictionary (read: JSON) object."
128        )
129        json_data = get_cfbd_poll_rankings(
130            api_key=cfbd_key,
131            season=2020,
132            week=10,
133            return_as_dict=True
134        )
135        print(json_data)
136
137    else:
138        # Alternatively, if the CFBD API key exists in this python environment,
139        # or it's been set by cfbd_json_py.utls.set_cfbd_api_token(),
140        # you could just call these functions directly,
141        # without setting the API key in the script.
142        print(
143            "Using the user's API key supposedly loaded into " +
144            "this python environment for this example."
145        )
146
147        # Get CFB poll data for the 2020 CFB season.
148        print("Get CFB poll data for the 2020 CFB season.")
149        json_data = get_cfbd_poll_rankings(
150            season=2020
151        )
152        print(json_data)
153        time.sleep(5)
154
155        # Get CFB poll data from week 10 of the 2023 CFB season.
156        print("Get CFB poll data from week 10 of the 2023 CFB season.")
157        json_data = get_cfbd_poll_rankings(
158            season=2023,
159            week=10
160        )
161        print(json_data)
162        time.sleep(5)
163
164        # Get CFB poll data for the 2021 CFB season, during the postseason.
165        print(
166            "Get CFB poll data for the 2021 CFB season, during the postseason."
167        )
168        json_data = get_cfbd_poll_rankings(
169            season=2021,
170            season_type="postseason"
171        )
172        print(json_data)
173        time.sleep(5)
174
175        # You can also tell this function to just return the API call as
176        # a Dictionary (read: JSON) object.
177        print(
178            "You can also tell this function to just return the API call " +
179            "as a dictionary (read: JSON) object."
180        )
181        json_data = get_cfbd_poll_rankings(
182            season=2020,
183            week=10,
184            return_as_dict=True
185        )
186        print(json_data)
187
188    ```
189    Returns
190    ----------
191    A pandas `DataFrame` object with CFB Poll data,
192    or (if `return_as_dict` is set to `True`)
193    a dictionary object with CFB Poll data.
194
195
196    """
197    now = datetime.now()
198    rankings_df = pd.DataFrame()
199    row_df = pd.DataFrame()
200    url = "https://api.collegefootballdata.com/rankings"
201
202    ##########################################################################
203
204    if api_key is not None:
205        real_api_key = api_key
206        del api_key
207    else:
208        real_api_key = get_cfbd_api_token(api_key_dir=api_key_dir)
209
210    if real_api_key == "tigersAreAwesome":
211        raise ValueError(
212            "You actually need to change `cfbd_key` to your CFBD API key."
213        )
214    elif "Bearer " in real_api_key:
215        pass
216    elif "Bearer" in real_api_key:
217        real_api_key = real_api_key.replace("Bearer", "Bearer ")
218    else:
219        real_api_key = "Bearer " + real_api_key
220
221    if season is None:
222        # This should never happen without user tampering, but if it does,
223        # we need to raise an error,
224        # because the CFBD API will refuse this call without a valid season.
225        raise SystemError(
226            "I don't know how, I don't know why, "
227            + "but you managed to call this function "
228            + "while `season` was `None` (NULL),"
229            + " and the function got to this point in the code."
230            + "\nIf you have a GitHub account, "
231            + "please raise an issue on this python package's GitHub page:\n"
232            + "https://github.com/armstjc/cfbd-json-py/issues"
233        )
234    elif season > (now.year + 1):
235        raise ValueError(f"`season` cannot be greater than {season}.")
236    elif season < 1869:
237        raise ValueError("`season` cannot be less than 1869.")
238
239    if season_type != "regular" and season_type != "postseason":
240        raise ValueError(
241            '`season_type` must be set to either ' +
242            '"regular" or "postseason" for this function to work.'
243        )
244
245    if week is not None and week < 0:
246        raise ValueError("`week` must be a positive number.")
247
248    if season_type != "regular" and season_type != "postseason":
249        raise ValueError(
250            '`season_type` must be set to either ' +
251            '"regular" or "postseason" for this function to work.'
252        )
253    # URL builder
254    ##########################################################################
255
256    # Required by API
257    url += f"?year={season}"
258
259    if week is not None:
260        url += f"&week={week}"
261
262    if season_type is not None:
263        url += f"&seasonType={season_type}"
264
265    headers = {
266        "Authorization": f"{real_api_key}", "accept": "application/json"
267    }
268    response = requests.get(url, headers=headers)
269
270    if response.status_code == 200:
271        pass
272    elif response.status_code == 401:
273        raise ConnectionRefusedError(
274            "Could not connect. " +
275            "The connection was refused.\nHTTP Status Code 401."
276        )
277    else:
278        raise ConnectionError(
279            f"Could not connect.\nHTTP Status code {response.status_code}"
280        )
281
282    json_data = response.json()
283
284    if return_as_dict is True:
285        return json_data
286
287    for week in json_data:
288        w_season = week["season"]
289        w_season_type = week["seasonType"]
290        w_week = week["week"]
291
292        for poll in week["polls"]:
293            p_poll_name = poll["poll"]
294
295            for team in poll["ranks"]:
296                row_df = pd.DataFrame(
297                    {
298                        "season": w_season,
299                        "season_type": w_season_type,
300                        "week": w_week,
301                        "poll_name": p_poll_name,
302                    },
303                    index=[0],
304                )
305
306                row_df["poll_rank"] = team["rank"]
307                row_df["school_name"] = team["school"]
308                row_df["conference_name"] = team["conference"]
309                row_df["first_place_votes"] = team["firstPlaceVotes"]
310                row_df["points"] = team["points"]
311
312                rankings_df = pd.concat(
313                    [rankings_df, row_df],
314                    ignore_index=True
315                )
316                del row_df
317
318            del p_poll_name
319
320        del w_season, w_season_type, w_week
321    return rankings_df