oddsapiR

oddsapiR is an R package for accessing live and historical sports betting odds, scores, events, and participants from The Odds API — spanning dozens of sports and 60+ bookmakers worldwide. Every endpoint returns a clean, tidy data.frame/tibble ready for analysis, built on a single httr2-based request layer with automatic API-key handling and usage-quota tracking.

Part of the SportsDataverse family of R & Python packages for sports analytics. To access the API, get a free API key at https://the-odds-api.com.

Data freshness and pipeline status for every SportsDataverse dataset: sportsdataverse.org/status.

Installation

You can install the CRAN version of oddsapiR with:

install.packages("oddsapiR")

You can install the latest build from R-universe with:

install.packages("oddsapiR", repos = c("https://sportsdataverse.r-universe.dev", getOption("repos")))

You can install the development version of oddsapiR from GitHub with:

if (!requireNamespace("pak", quietly = TRUE)) install.packages("pak")
pak::pak("sportsdataverse/oddsapiR")
# or, with remotes:
# if (!requireNamespace("remotes", quietly = TRUE)) install.packages("remotes")
# remotes::install_github("sportsdataverse/oddsapiR")

# or clone and install locally
git clone https://github.com/sportsdataverse/oddsapiR
cd oddsapiR
Rscript -e "pak::local_install()"  # or: Rscript -e "devtools::install()"

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")

Quick start

With ODDS_API_KEY set (see above):

library(oddsapiR)

# sports that are in season, with the sport_key each endpoint takes
toa_sports(all_sports = FALSE)

# current NFL spreads from US bookmakers, in American odds
toa_sports_odds(sport_key = "americanfootball_nfl", regions = "us",
                markets = "spreads", odds_format = "american")

# NBA scores, including games completed in the last 3 days
toa_sports_scores(sport_key = "basketball_nba", days_from = 3)

# requests used and remaining after the last call
toa_quota()

Documentation

For more information on the package and function reference, please see the oddsapiR documentation website.

There is also a printable oddsapiR cheat sheet (PDF), one of a set covering every SportsDataverse package.

Breaking Changes

Full News on Releases

Companion packages

oddsapiR returns odds keyed by team names and start times; these packages supply the games, results and visuals to pair them with:

cfbfastR, hoopR, wehoop, fastRhockey and baseballr — schedules, scores and play-by-play to join odds onto.
sdvplotR — team logos, colors and gt tables for every SportsDataverse league. r-universe only.

The SportsDataverse

oddsapiR is part of the SportsDataverse, a set of open-source packages for sports data.

Package	Sport / Scope
cfbfastR	College football
hoopR	Men’s basketball (NBA and NCAA)
wehoop	Women’s basketball (WNBA and NCAA)
fastRhockey	Hockey (NHL and PWHL)
baseballr	Baseball (MLB, MiLB, NCAA)
softballR	College softball
oddsapiR	Sports betting odds
recruitR	College football recruiting
usfootballR	US soccer
cfbseedR · cfb4th	CFB playoff simulation · fourth-down decisions
cfbplotR · sdvplotR · sportyR	Logos, colors, tables · playing surfaces
sportsdataverse-R	Umbrella R metapackage
sportsdataverse-py · sportsdataverse.js	Python and Node.js

See the full ecosystem at sportsdataverse.org.

Follow the SportsDataverse on X and star this repo

Our Authors

Saiem Gilani

Cheat sheet

A printable one-page reference for oddsapiR — the function families, the loaders, and what each one returns.

📄 Download the oddsapiR cheat sheet (PDF)

Free to download, print and hand out; light and dark, US Letter landscape. Every SportsDataverse package has one — browse them all at sportsdataverse.org/cheatsheets.

Code of Conduct

Please note that the oddsapiR project is released with a Contributor Code of Conduct. By contributing to this project, you agree to abide by its terms.

Citations

To cite the oddsapiR R package in publications, use:

BibTeX Citation

@misc{gilani_oddsapiR,
  author = {Gilani, Saiem},
  title = {oddsapiR: The SportsDataverse's R Package for The Odds API.},
  url = {https://oddsapiR.sportsdataverse.org},
  doi = {10.32614/CRAN.package.oddsapiR},
  year = {2026}
}