Assignment 6

BALLDONTLIE NBA API

For this assignment, I chose the BALLDONTLIE NBA API. This API is useful because it gives users access to basketball data such as players, teams, games, and stats. Someone may want to use this service if they are interested in basketball analytics, player lookups, team information, or building sports dashboards.

I chose this API because it is basketball related and simple to understand.

Loading Packages

library(tidyverse)
library(jsonlite)
library(magrittr)
library(httr)
library(knitr)

Setting Up The API

To use this API, I first had to create a free BALLDONTLIE account and get an API key from the website.

After getting the key, I can define the API key and the player endpoint in R.

api_key <- "YOUR_API_KEY_HERE"
bdl_endpoint <- "https://api.balldontlie.io/v1/players"

Building The Request URL

For my example, I decided to search for the player name “curry”. I also limited the results to 10 records.

search_term <-"curry"
per_page <- 10

player_url <- paste0(bdl_endpoint,"?search=", URLencode(search_term), "&per_page=", per_page)

player_url

This creates the URL for the player search request. The API key is still passed separately in the request header.

Making The API Call

Next, I use GET() from the httr package to request the data.

player_response <- 
  player_url %>%
  GET(add_headers(Authorization = api_key))

player_response$status_code

If the request works, the status code should be 200.

Turning The JSON Into A Data Frame

After retrieving the response, I can convert the JSON output into a usable data frame.

player_data <- 
  player_response %>%
  content(as = "text",
          encoding = "UTF-8") %>%
  fromJSON(flatten = TRUE)

players_df <- 
  player_data %>%
  use_series(data) %>%
  as_tibble() %>%
  transmute(id,
            first_name,
            last_name,
            position,
            height,
            weight,
            jersey_number,
            college,
            country,
            draft_year,
            draft_round,
            draft_number,
            team_id = team.id,
            team_full_name = team.full_name,
            team_abbreviation = team.abbreviation)

players_df

Creating A Function

To make the process easier, I can turn the code into a reusable function.

bdl_player_GET_df <- 
  function(api_key, search_term, per_page = 10) {
    player_url <- paste0("https://api.balldontlie.io/v1/players",
                         "?search=", URLencode(search_term),
                         "&per_page=", per_page)
    
    player_df <- 
      player_url %>%
      GET(add_headers(Authorization = api_key)) %>%
      content(as = "text",
              encoding = "UTF-8") %>%
      fromJSON(flatten = TRUE) %>%
      use_series(data) %>%
      as_tibble() %>%
      transmute(id,
                first_name,
                last_name,
                position,
                height,
                weight,
                jersey_number,
                college,
                country,
                draft_year,
                draft_round,
                draft_number,
                team_id = team.id,
                team_full_name = team.full_name,
                team_abbreviation = team.abbreviation)
    
    return(player_df)
  }

Demonstration

Below is an example of how I would run the function.

players_example <- 
  bdl_player_GET_df(api_key = api_key,
                    search_term = "curry",
                    per_page = 10)

Since I did not put my API key in here, I saved the results.

players_example <- read_csv("nba_players_example.csv", show_col_types = FALSE)

Here is the output:

id	first_name	last_name	position	height	weight	jersey_number	college	country	draft_year	draft_round	draft_number	team_id	team_full_name	team_abbreviation
114	Seth	Curry	G	6-1	185	31	Duke	USA	NA	NA	NA	10	Golden State Warriors	GSW
115	Stephen	Curry	G	6-2	185	30	Davidson	USA	2009	1	7	10	Golden State Warriors	GSW
817	Michael	Curry	NA	6-5	210	12	Georgia Southern	USA	NA	NA	NA	9	Detroit Pistons	DET
1376	Eddy	Curry	NA	7-0	295	34	Thornwood HS (IL)	USA	2001	1	4	5	Chicago Bulls	CHI
1790	JamesOn	Curry	NA	6-3	190	20	Oklahoma State	USA	2007	2	51	13	LA Clippers	LAC
2719	Carey	Scurry	NA	6-7	188	20	Long Island-Brooklyn	USA	1985	2	37	29	Utah Jazz	UTA
2948	Dell	Curry	NA	6-5	205	30	Virginia Tech	USA	1986	1	15	4	Charlotte Hornets	CHA

This shows that the API returned player information successfully and that the JSON response can be turned into a clean table for analysis.

Conclusion

Overall, the BALLDONTLIE NBA API is a simple and useful API for basketball data in R. It is a good example of how to build a request URL, make a GET() call, convert JSON to a data frame, and create a reusable function.