Skip to contents

Getting started with oddsapiR

Saiem Gilani
@saiemgilani @saiemgilani

Source: vignettes/oddsapiR.Rmd
oddsapiR.Rmd

Welcome folks,

I’m Saiem Gilani, one of the authors of oddsapiR, and I hope to give the community a high-quality resource for accessing The Odds API.

Install oddsapiR 

# You can install using the pacman package using the following code:
if (!requireNamespace('pacman', quietly = TRUE)){
  install.packages('pacman')
}
pacman::p_load_current_gh("sportsdataverse/oddsapiR", dependencies = TRUE, update = TRUE)
pacman::p_load_current_gh("jthomasmock/gtExtras", dependencies = TRUE, update = TRUE)
pacman::p_load(dplyr, knitr, gt)

Odds API Keys

The Odds API requires an API key, here’s a quick run-down:

  • Using the key: You can save the key for consistent usage by adding ODDS_API_KEY=XXXX-YOUR-API-KEY-HERE-XXXXX to your .Renviron file (easily accessed via usethis::edit_r_environ()). Run usethis::edit_r_environ(), a new script will pop open named .Renviron, THEN paste the following in the new script that pops up (without quotations)
ODDS_API_KEY = XXXX-YOUR-API-KEY-HERE-XXXXX

Save the script and restart your RStudio session, by clicking Session (in between Plots and Build) and click Restart R (there also exists the shortcut Ctrl + Shift + F10 to restart your session). If set correctly, from then on you should be able to use any of the functions without any other changes.

  • For less consistent usage: At the beginning of every session or within an R environment, save your API key as the environment variable ODDS_API_KEY (with quotations) using a command like the following.
Sys.setenv(ODDS_API_KEY = "XXXX-YOUR-API-KEY-HERE-XXXXX")

The included data

toa_sports_keys - The sports for which The Odds API provides coverage

oddsapiR::toa_sports_keys %>%
  gt() %>% 
  gtExtras::gt_theme_538(table.width = px(650))
key group title description has_outrights
americanfootball_ncaaf American Football NCAAF US College Football FALSE
americanfootball_nfl American Football NFL US Football FALSE
americanfootball_nfl_super_bowl_winner American Football NFL Super Bowl Winner Super Bowl Winner 2022/2023 TRUE
aussierules_afl Aussie Rules AFL Aussie Football FALSE
baseball_mlb Baseball MLB Major League Baseball FALSE
baseball_mlb_world_series_winner Baseball MLB World Series Winner World Series Winner 2022 TRUE
basketball_euroleague Basketball Basketball Euroleague Basketball Euroleague FALSE
basketball_nba Basketball NBA US Basketball FALSE
basketball_nba_championship_winner Basketball NBA Championship Winner Championship Winner 2021/2022 TRUE
basketball_ncaab Basketball NCAAB US College Basketball FALSE
basketball_wnba Basketball WNBA US Basketball FALSE
cricket_big_bash Cricket Big Bash Big Bash League FALSE
cricket_icc_world_cup Cricket ICC World Cup ICC World Cup FALSE
cricket_ipl Cricket IPL Indian Premier League FALSE
cricket_odi Cricket One Day Internationals One Day Internationals FALSE
cricket_test_match Cricket Test Matches International Test Matches FALSE
golf_masters_tournament_winner Golf Masters Tournament Winner 2023 Winner TRUE
golf_pga_championship_winner Golf PGA Championship Winner 2022 Winner TRUE
golf_the_open_championship_winner Golf The Open Winner 2022 Winner TRUE
golf_us_open_winner Golf US Open Winner 2022 Winner TRUE
icehockey_nhl Ice Hockey NHL US Ice Hockey FALSE
icehockey_nhl_championship_winner Ice Hockey NHL Championship Winner Stanley Cup Winner 2021/2022 TRUE
icehockey_sweden_allsvenskan Ice Hockey HockeyAllsvenskan Swedish Hockey Allsvenskan FALSE
icehockey_sweden_hockey_league Ice Hockey SHL Swedish Hockey League FALSE
mma_mixed_martial_arts Mixed Martial Arts MMA Mixed Martial Arts FALSE
politics_us_presidential_election_winner Politics US Presidential Elections Winner 2024 US Presidential Election Winner TRUE
rugbyleague_nrl Rugby League NRL Aussie Rugby League FALSE
soccer_africa_cup_of_nations Soccer Africa Cup of Nations Africa Cup of Nations FALSE
soccer_argentina_primera_division Soccer Primera División - Argentina Argentine Primera División FALSE
soccer_australia_aleague Soccer A-League Aussie Soccer FALSE
soccer_belgium_first_div Soccer Belgium First Div Belgian First Division A FALSE
soccer_brazil_campeonato Soccer Brazil Série A Brasileirão Série A FALSE
soccer_china_superleague Soccer Super League - China FALSE
soccer_conmebol_copa_libertadores Soccer Copa Libertadores CONMEBOL Copa Libertadores FALSE
soccer_denmark_superliga Soccer Denmark Superliga FALSE
soccer_efl_champ Soccer Championship EFL Championship FALSE
soccer_england_efl_cup Soccer EFL Cup League Cup FALSE
soccer_england_league1 Soccer League 1 EFL League 1 FALSE
soccer_england_league2 Soccer League 2 EFL League 2 FALSE
soccer_epl Soccer EPL English Premier League FALSE
soccer_fa_cup Soccer FA Cup Football Association Challenge Cup FALSE
soccer_fifa_world_cup Soccer FIFA World Cup FIFA World Cup 2022 FALSE
soccer_fifa_world_cup_winner Soccer FIFA World Cup Winner FIFA World Cup Winner 2022 TRUE
soccer_finland_veikkausliiga Soccer Veikkausliiga - Finland FALSE
soccer_france_ligue_one Soccer Ligue 1 - France FALSE
soccer_france_ligue_two Soccer Ligue 2 - France French Soccer FALSE
soccer_germany_bundesliga Soccer Bundesliga - Germany German Soccer FALSE
soccer_germany_bundesliga2 Soccer Bundesliga 2 - Germany German Soccer FALSE
soccer_italy_serie_a Soccer Serie A - Italy Italian Soccer FALSE
soccer_italy_serie_b Soccer Serie B - Italy Italian Soccer FALSE
soccer_japan_j_league Soccer J League Japan Soccer League FALSE
soccer_korea_kleague1 Soccer K League 1 Korean Soccer FALSE
soccer_league_of_ireland Soccer League of Ireland Airtricity League Premier Division FALSE
soccer_mexico_ligamx Soccer Liga MX Mexican Soccer FALSE
soccer_netherlands_eredivisie Soccer Dutch Eredivisie Dutch Soccer FALSE
soccer_norway_eliteserien Soccer Eliteserien - Norway Norwegian Soccer FALSE
soccer_portugal_primeira_liga Soccer Primeira Liga - Portugal Portugese Soccer FALSE
soccer_russia_premier_league Soccer Premier League - Russia Russian Soccer FALSE
soccer_spain_la_liga Soccer La Liga - Spain Spanish Soccer FALSE
soccer_spain_segunda_division Soccer La Liga 2 - Spain Spanish Soccer FALSE
soccer_spl Soccer Premiership - Scotland Scottish Premiership FALSE
soccer_sweden_allsvenskan Soccer Allsvenskan - Sweden Swedish Soccer FALSE
soccer_sweden_superettan Soccer Superettan - Sweden Swedish Soccer FALSE
soccer_switzerland_superleague Soccer Swiss Superleague Swiss Soccer FALSE
soccer_turkey_super_league Soccer Turkey Super League Turkish Soccer FALSE
soccer_uefa_champs_league Soccer UEFA Champions European Champions League FALSE
soccer_uefa_europa_league Soccer UEFA Europa European Europa League FALSE
soccer_uefa_nations_league Soccer UEFA Nations League UEFA Nations League FALSE
soccer_usa_mls Soccer MLS Major League Soccer FALSE
tennis_atp_aus_open_singles Tennis ATP Australian Open Men's Singles FALSE
tennis_atp_french_open Tennis ATP French Open Men's Singles FALSE
tennis_atp_us_open Tennis ATP US Open Men's Singles FALSE
tennis_atp_wimbledon Tennis ATP Wimbledon Men's Singles FALSE
tennis_wta_aus_open_singles Tennis WTA Australian Open Women's Singles FALSE
tennis_wta_french_open Tennis WTA French Open Women's Singles FALSE
tennis_wta_us_open Tennis WTA US Open Women's Singles FALSE
tennis_wta_wimbledon Tennis WTA Wimbledon Women's Singles FALSE

Three core functions

One endpoint for looking up the sports the API provides (including currently active status): toa_sports


oddsapiR::toa_sports(all_sports = TRUE) %>%
  head(n=10) %>% 
  gt() %>% 
  gtExtras::gt_theme_538(table.width = px(550))
key group title description active has_outrights
americanfootball_cfl American Football CFL Canadian Football League FALSE FALSE
americanfootball_ncaaf American Football NCAAF US College Football TRUE FALSE
americanfootball_nfl American Football NFL US Football FALSE FALSE
americanfootball_nfl_preseason American Football NFL Preseason US Football FALSE FALSE
americanfootball_nfl_super_bowl_winner American Football NFL Super Bowl Winner Super Bowl Winner 2023/2024 TRUE TRUE
americanfootball_xfl American Football XFL US Football TRUE FALSE
aussierules_afl Aussie Rules AFL Aussie Football TRUE FALSE
baseball_mlb Baseball MLB Major League Baseball FALSE FALSE
baseball_mlb_preseason Baseball MLB Preseason Major League Baseball TRUE FALSE
baseball_mlb_world_series_winner Baseball MLB World Series Winner World Series Winner 2023 TRUE TRUE

One endpoint for looking up the current odds from the API: toa_sports_odds

oddsapiR::toa_sports_odds(sport_key = 'basketball_nba', 
                          regions = 'us', 
                          markets = 'spreads', 
                          odds_format = 'decimal',
                          date_format = 'iso') %>% 
  dplyr::select(c("bookmaker","market_key", "outcomes_name","outcomes_price","outcomes_point","home_team","away_team","commence_time")) %>% 
  head(n=20) %>% 
  knitr::kable()
bookmaker market_key outcomes_name outcomes_price outcomes_point home_team away_team commence_time
DraftKings spreads Brooklyn Nets 2.35 11.5 Brooklyn Nets Denver Nuggets 2023-03-19T19:40:00Z
DraftKings spreads Denver Nuggets 1.61 -11.5 Brooklyn Nets Denver Nuggets 2023-03-19T19:40:00Z
MyBookie.ag spreads Brooklyn Nets 1.91 2.5 Brooklyn Nets Denver Nuggets 2023-03-19T19:40:00Z
MyBookie.ag spreads Denver Nuggets 1.91 -2.5 Brooklyn Nets Denver Nuggets 2023-03-19T19:40:00Z
BetMGM spreads Brooklyn Nets 1.95 12.5 Brooklyn Nets Denver Nuggets 2023-03-19T19:40:00Z
BetMGM spreads Denver Nuggets 1.80 -12.5 Brooklyn Nets Denver Nuggets 2023-03-19T19:40:00Z
FanDuel spreads Brooklyn Nets 2.04 10.5 Brooklyn Nets Denver Nuggets 2023-03-19T19:40:00Z
FanDuel spreads Denver Nuggets 1.74 -10.5 Brooklyn Nets Denver Nuggets 2023-03-19T19:40:00Z
FOX Bet spreads Brooklyn Nets 1.80 9.5 Brooklyn Nets Denver Nuggets 2023-03-19T19:40:00Z
FOX Bet spreads Denver Nuggets 1.85 -9.5 Brooklyn Nets Denver Nuggets 2023-03-19T19:40:00Z
BetRivers spreads Brooklyn Nets 1.91 9.0 Brooklyn Nets Denver Nuggets 2023-03-19T19:40:00Z
BetRivers spreads Denver Nuggets 1.85 -9.0 Brooklyn Nets Denver Nuggets 2023-03-19T19:40:00Z
SugarHouse spreads Brooklyn Nets 1.91 9.0 Brooklyn Nets Denver Nuggets 2023-03-19T19:40:00Z
SugarHouse spreads Denver Nuggets 1.85 -9.0 Brooklyn Nets Denver Nuggets 2023-03-19T19:40:00Z
Barstool Sportsbook spreads Brooklyn Nets 1.91 9.0 Brooklyn Nets Denver Nuggets 2023-03-19T19:40:00Z
Barstool Sportsbook spreads Denver Nuggets 1.87 -9.0 Brooklyn Nets Denver Nuggets 2023-03-19T19:40:00Z
TwinSpires spreads Brooklyn Nets 1.92 9.0 Brooklyn Nets Denver Nuggets 2023-03-19T19:40:00Z
TwinSpires spreads Denver Nuggets 1.85 -9.0 Brooklyn Nets Denver Nuggets 2023-03-19T19:40:00Z
Unibet spreads Brooklyn Nets 1.96 9.0 Brooklyn Nets Denver Nuggets 2023-03-19T19:40:00Z
Unibet spreads Denver Nuggets 1.82 -9.0 Brooklyn Nets Denver Nuggets 2023-03-19T19:40:00Z

Note: There are two entries per event per bookmaker for the spreads for both sides of the event.

One endpoint for looking up the current scores from the API: toa_sports_scores

oddsapiR::toa_sports_scores(sport_key = 'basketball_nba', 
                            days_from = NULL,
                            date_format = 'iso') %>% 
  head(n=20) %>% 
  knitr::kable()
id sport_key sport_title commence_time completed home_team away_team scores last_update
2b445376898e6149a800ecdcdbfdd1e0 basketball_nba NBA 2023-03-19T19:40:00Z FALSE Brooklyn Nets Denver Nuggets Brooklyn Nets , Denver Nuggets, 99 , 108 2023-03-19T21:43:48Z
7e491eeda173814fb7ef9484ec86f4ff basketball_nba NBA 2023-03-19T19:40:00Z FALSE Oklahoma City Thunder Phoenix Suns Oklahoma City Thunder, Phoenix Suns , 108 , 103 2023-03-19T21:43:48Z
e73cd557a7d61739eee6029fde557dd4 basketball_nba NBA 2023-03-19T20:10:00Z FALSE San Antonio Spurs Atlanta Hawks San Antonio Spurs, Atlanta Hawks , 95 , 97 2023-03-19T21:43:48Z
6bb389f82f1fc15d3342ca1cdfdae4cd basketball_nba NBA 2023-03-19T22:10:00Z FALSE Detroit Pistons Miami Heat NULL 2023-03-19T19:46:34Z
16562d32b2a2f3847b42d16d980bf03a basketball_nba NBA 2023-03-19T23:10:00Z FALSE Houston Rockets New Orleans Pelicans NULL 2023-03-19T19:46:34Z
63ad16c06fa6d2a78b33675a21e5af1b basketball_nba NBA 2023-03-20T00:10:00Z FALSE Milwaukee Bucks Toronto Raptors NULL 2023-03-19T19:46:34Z
db2fdc0c07ca0eb98c08ef1f0c307521 basketball_nba NBA 2023-03-20T01:10:00Z FALSE Portland Trail Blazers Los Angeles Clippers NULL 2023-03-19T19:46:34Z
f9b5e9c69fc15e03231ad4fcf2a6cc34 basketball_nba NBA 2023-03-20T01:40:00Z FALSE Los Angeles Lakers Orlando Magic NULL 2023-03-19T19:46:34Z
88984256f5bdbc7c57023a9fea41adbc basketball_nba NBA 2023-03-20T23:10:00Z FALSE Charlotte Hornets Indiana Pacers NULL NA
b68b438f7e14f26711dda3d6d40cda15 basketball_nba NBA 2023-03-20T23:10:00Z FALSE Philadelphia 76ers Chicago Bulls NULL NA
405ddefffd9f5dcd59a14863233882e1 basketball_nba NBA 2023-03-20T23:40:00Z FALSE New York Knicks Minnesota Timberwolves NULL NA
c89b602a63ac8bf052af036e4e06f58c basketball_nba NBA 2023-03-21T00:10:00Z FALSE Houston Rockets Golden State Warriors NULL NA
dddb397ab70e1cd3a2362d6864861f4a basketball_nba NBA 2023-03-21T01:10:00Z FALSE Utah Jazz Sacramento Kings NULL NA

Our Authors

Citations

To cite the oddsapiR R package in publications, use:

BibTex Citation

@misc{gilani_2022_oddsapiR,
  author = {Gilani, Saiem},
  title = {oddsapiR: The SportsDataverse's R Package for The Odds API.},
  url = {https://oddsapiR.sportsdataverse.org},
  year = {2022}
}