cfbd_json_py.venues

  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: venues.py
  5# Purpose: Houses functions pertaining to
  6#    CFB team venues/stadium data within the CFBD API.
  7###############################################################################
  8
  9import pandas as pd
 10import requests
 11
 12from cfbd_json_py.utls import get_cfbd_api_token
 13
 14
 15def get_cfbd_venues(
 16    api_key: str = None,
 17    api_key_dir: str = None,
 18    return_as_dict: bool = False
 19):
 20    """
 21    Allows a user to get CFB venue/stadium information from the CFBD API.
 22
 23    Parameters
 24    ----------
 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.venues import get_cfbd_venues
 57
 58
 59    cfbd_key = "tigersAreAwesome"  # placeholder for your CFBD API Key.
 60
 61    if cfbd_key != "tigersAreAwesome":
 62        print(
 63            "Using the user's API key declared in this script " +
 64            "for this example."
 65        )
 66
 67        # Get CFB venue/stadium data from the CFBD API.
 68        print("Get CFB venue/stadium data from the CFBD API.")
 69        json_data = get_cfbd_venues(
 70            api_key=cfbd_key
 71        )
 72        print(json_data)
 73        time.sleep(5)
 74
 75        # You can also tell this function to just return the API call as
 76        # a Dictionary (read: JSON) object.
 77        print(
 78            "You can also tell this function to just return the API call " +
 79            "as a Dictionary (read: JSON) object."
 80        )
 81        json_data = get_cfbd_venues(
 82            api_key=cfbd_key,
 83            return_as_dict=True
 84        )
 85        print(json_data)
 86
 87    else:
 88        # Alternatively, if the CFBD API key exists in this python environment,
 89        # or it's been set by cfbd_json_py.utls.set_cfbd_api_token(),
 90        # you could just call these functions directly,
 91        # without setting the API key in the script.
 92        print(
 93            "Using the user's API key supposedly loaded into " +
 94            "this python environment for this example."
 95        )
 96
 97        # Get CFB venue/stadium data from the CFBD API.
 98        print("Get CFB venue/stadium data from the CFBD API.")
 99        json_data = get_cfbd_venues()
100        print(json_data)
101        time.sleep(5)
102
103
104        # You can also tell this function to just return the API call as
105        # a Dictionary (read: JSON) object.
106        print(
107            "You can also tell this function to just return the API call " +
108            "as a Dictionary (read: JSON) object."
109        )
110        json_data = get_cfbd_venues(
111            return_as_dict=True
112        )
113        print(json_data)
114
115    ```
116    Returns
117    ----------
118    A pandas `DataFrame` object with CFB venue/stadium information,
119    or (if `return_as_dict` is set to `True`)
120    a dictionary object with with CFB venue/stadium information.
121
122    """
123    venue_df = pd.DataFrame()
124    url = "https://api.collegefootballdata.com/venues"
125
126    ##########################################################################
127
128    if api_key is not None:
129        real_api_key = api_key
130        del api_key
131    else:
132        real_api_key = get_cfbd_api_token(api_key_dir=api_key_dir)
133
134    if real_api_key == "tigersAreAwesome":
135        raise ValueError(
136            "You actually need to change `cfbd_key` to your CFBD API key."
137        )
138    elif "Bearer " in real_api_key:
139        pass
140    elif "Bearer" in real_api_key:
141        real_api_key = real_api_key.replace("Bearer", "Bearer ")
142    else:
143        real_api_key = "Bearer " + real_api_key
144
145    ##########################################################################
146
147    headers = {
148        "Authorization": f"{real_api_key}",
149        "accept": "application/json"
150    }
151
152    response = requests.get(url, headers=headers)
153
154    if response.status_code == 200:
155        pass
156    elif response.status_code == 401:
157        raise ConnectionRefusedError(
158            "Could not connect. The connection was refused.\n" +
159            "HTTP Status Code 401."
160        )
161    else:
162        raise ConnectionError(
163            f"Could not connect.\nHTTP Status code {response.status_code}"
164        )
165
166    json_data = response.json()
167
168    if return_as_dict is True:
169        return json_data
170
171    venue_df = pd.json_normalize(json_data)
172    venue_df.rename(
173        columns={
174            "id": "venue_id",
175            "name": "venue_name",
176            "capacity": "venue_capacity",
177            "grass": "is_grass",
178            "city": "venue_city",
179            "state": "venue_state",
180            "zip": "venue_zip_code",
181            "country_code": "venue_country_code",
182            "elevation": "venue_elevation",
183            "dome": "is_dome",
184            "location.x": "venue_location_x",
185            "location.y": "venue_location_y",
186        },
187        inplace=True,
188    )
189    return venue_df