Package 'oddsapiR'

Description

This is a thin wrapper on data.table::fread

Usage

csv_from_url(...)

Arguments

Value

a dataframe as created by data.table::fread()

Description

This function helps add progress-reporting to any function - given function f() and progressor p(), it will return a new function that calls f() and then (on-exiting) will call p() after every iteration.

Usage

progressively(f, p = NULL)

Arguments

Details

This is inspired by purrr's safely, quietly, and possibly function decorators.

Value

a function that does the same as f but it calls p() after iteration.

Description

Load .rds file from a remote connection

Usage

rds_from_url(url)

Arguments

Value

a dataframe as created by readRDS()

Description

Save your API Key as a system environment variable ODDS_API_KEY

Usage

toa_key()

has_toa_key()

check_toa_key()

Details

To get access to an API key, follow the instructions at https://the-odds-api.com

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

Value

Called as a side-effect to ensure that a user has an API key stored in their environment before making a call to the Odds API service.

See Also

toa_quota() to inspect your usage credits after any API call, toa_requests() to explicitly query your remaining/used credits, and toa_sports() to start exploring available sports. Part of the SportsDataverse.

Other The Odds API: Account & Usage: toa_quota(), toa_requests()

Description

Get the available market keys for each bookmaker for a single event.

Returns the recently seen market keys per bookmaker for an event (no odds). This is not a comprehensive list of all supported markets – more keys are returned as bookmakers open more markets approaching commence time. Use the returned market_key values to request odds via toa_event_odds().

Usage quota cost: 1 credit.

Usage

toa_event_markets(
  sport_key,
  event_id,
  regions = "us",
  bookmakers = NULL,
  date_format = "iso"
)

Arguments

Value

A tibble with one row per bookmaker market available for the event:

See Also

toa_event_odds() to pull odds for the market keys discovered here, toa_sports_odds() for featured-market odds across all events, and toa_sports_events() to look up event_id values. Part of the SportsDataverse.

Other The Odds API: Odds & Markets: toa_event_odds(), toa_sports_odds()

Examples

try(toa_event_markets(sport_key = 'basketball_nba',
                         event_id = '48db9c3293a52baab881d95d38f37a98',
                         regions = 'us'))

Description

Get bookmaker odds for a single event from The Odds API.

Unlike toa_sports_odds() (featured markets only), this endpoint accepts any available market key, including player props and alternate lines. Look up an event_id with toa_sports_events().

Usage quota cost: ⁠[number of unique markets returned] x [number of regions]⁠.

Usage

toa_event_odds(
  sport_key,
  event_id,
  regions = "us",
  markets = "spreads",
  odds_format = "decimal",
  date_format = "iso",
  bookmakers = NULL
)

Arguments

Value

A long-format tibble with one row per bookmaker market outcome:

See Also

toa_sports_odds() for featured-market odds across all upcoming events, toa_event_markets() to discover available market keys for an event, and toa_sports_events() to look up event_id values. Part of the SportsDataverse.

Other The Odds API: Odds & Markets: toa_event_markets(), toa_sports_odds()

Examples

try(toa_event_odds(sport_key = 'basketball_nba',
                      event_id = '48db9c3293a52baab881d95d38f37a98',
                      regions = 'us',
                      markets = 'player_points',
                      odds_format = 'decimal',
                      date_format = 'iso'))

Description

Get bookmaker odds for a single event as they appeared at a point in time.

Like toa_event_odds() but for a historical snapshot: accepts any available market key (including player props and alternate lines) and returns the odds at the snapshot closest to (and at or before) the requested date. Look up a historical event_id with toa_sports_events_history(). The returned timestamp, previous_timestamp and next_timestamp columns let you page through snapshots.

Historical odds for additional markets are available from 2023-05-03 at 5-minute intervals; featured markets reach back to June 2020 on paid plans.

Usage quota cost: ⁠[number of unique markets returned] x [number of regions]⁠ (the standard rate, not the 10x historical multiplier). Snapshots with no data do not count against the quota.

Usage

toa_event_odds_history(
  sport_key,
  event_id,
  date,
  regions = "us",
  markets = "h2h",
  odds_format = "decimal",
  date_format = "iso",
  bookmakers = NULL
)

Arguments

Value

A long-format tibble with one row per bookmaker market outcome:

See Also

toa_sports_events_history() to look up historical event_id values, toa_sports_odds_history() for featured-market odds across all events at a snapshot, and toa_event_odds() for current event odds. Part of the SportsDataverse.

Other The Odds API: Historical: toa_sports_events_history(), toa_sports_odds_history()

Examples

try(toa_event_odds_history(sport_key = 'basketball_nba',
                              event_id = '93af4b300a4c0dded909234ea32e9abd',
                              date = '2024-01-15T12:15:00Z',
                              regions = 'us',
                              markets = 'h2h',
                              odds_format = 'decimal',
                              date_format = 'iso'))

Description

Returns the usage-quota headers reported by The Odds API on the most recent ⁠toa_*()⁠ call made in this R session. The Odds API returns three headers with every response:

• x-requests-remaining – usage credits remaining until the quota resets

• x-requests-used – usage credits used since the last quota reset

• x-requests-last – the usage cost of the last API call

These same values are attached as attributes (oddsapiR_requests_remaining, oddsapiR_requests_used, oddsapiR_requests_last) to every tibble returned by a ⁠toa_*()⁠ function, and are echoed when the tibble is printed.

Usage

toa_quota()

Value

A one-row tibble with columns requests_remaining, requests_used and requests_last, or NULL if no API call has been made yet this session.

See Also

toa_requests() to explicitly query usage via an API round-trip, toa_key() / register_toa to set up your API key, and toa_sports() for your first data call. Part of the SportsDataverse.

Other The Odds API: Account & Usage: register_toa, toa_requests()

Examples

try(toa_sports())
  try(toa_quota())

Description

Get your usage and remaining calls for your key from The Odds API.

The values are read from the x-requests-remaining and x-requests-used response headers returned with every API call. This check is performed against the free ⁠/v4/sports⁠ endpoint, so it does not consume any quota.

Usage quota cost: Free.

Usage

toa_requests()

Value

A tibble of The Odds API key usage with the following columns:

See Also

toa_quota() to read cached usage from the most recent call without a network round-trip, toa_key() / register_toa to configure your API key, and toa_sports() to start pulling data. Part of the SportsDataverse.

Other The Odds API: Account & Usage: register_toa, toa_quota()

Examples

try(toa_requests())

Description

Get the sports for which The Odds API provides coverage.

Returns a list of in-season sports. The key returned here is the sport_key consumed by every other ⁠toa_*()⁠ endpoint.

Usage quota cost: Free. This endpoint does not count against your quota.

Usage

toa_sports(all_sports = TRUE)

Arguments

Value

A tibble of the sports for which The Odds API provides coverage:

See Also

toa_sports_events() to list upcoming events for a sport, toa_sports_scores() for live/recent scores, and toa_sports_odds() to pull featured-market odds. Part of the SportsDataverse.

Other The Odds API: Sports & Events: toa_sports_events(), toa_sports_participants(), toa_sports_scores()

Examples

try(toa_sports(all_sports = TRUE))

Description

Get the list of in-play and pre-match events for a sport.

Returns a list of events without odds. The id returned here is the event_id consumed by toa_event_odds() and toa_event_markets().

Usage quota cost: Free. This endpoint does not count against your quota.

Usage

toa_sports_events(
  sport_key,
  date_format = "iso",
  event_ids = NULL,
  commence_time_from = NULL,
  commence_time_to = NULL,
  include_rotation_numbers = FALSE
)

Arguments

Value

A tibble with one row per event:

See Also

toa_sports() to discover sport_key values, toa_event_odds() to pull odds for a specific event by its id, and toa_event_markets() to see available market keys per bookmaker. Part of the SportsDataverse.

Other The Odds API: Sports & Events: toa_sports(), toa_sports_participants(), toa_sports_scores()

Examples

try(toa_sports_events(sport_key = 'basketball_nba'))

Description

Get the list of events for a sport as they appeared at a point in time.

Returns the events (without odds) that existed at the snapshot closest to (and at or before) the requested date. The returned timestamp, previous_timestamp and next_timestamp columns let you page through snapshots. The id returned here is the event_id consumed by toa_event_odds_history().

Historical data is available on paid usage plans from June 2020.

Usage quota cost: 1 credit (0 if no events are found at the snapshot).

Usage

toa_sports_events_history(
  sport_key,
  date,
  date_format = "iso",
  event_ids = NULL,
  commence_time_from = NULL,
  commence_time_to = NULL,
  include_rotation_numbers = FALSE
)

Arguments

Value

A tibble with one row per historical event:

See Also

toa_event_odds_history() to pull odds for a historical event by its id, toa_sports_odds_history() for featured-market odds at a historical snapshot, and toa_sports_events() for current events. Part of the SportsDataverse.

Other The Odds API: Historical: toa_event_odds_history(), toa_sports_odds_history()

Examples

try(toa_sports_events_history(sport_key = 'basketball_nba',
                                 date = '2024-01-15T12:15:00Z'))

Description

A data set mapping Sports Events/League names to keys for end-user ease.

Usage

data(toa_sports_keys)

Format

A data frame with 5 variables:

key - Sport key group - Sport group (non-league description) title - Sport title description - Sport description has_outrights - Whether the sport or event has outright victories.

Description

Get the featured-market odds for a sport which The Odds API covers.

Returns a list of upcoming and live games with featured bookmaker odds for the specified markets and regions. For player props and other additional markets, use toa_event_odds() instead.

Usage quota cost: ⁠[number of markets] x [number of regions]⁠.

Usage

toa_sports_odds(
  sport_key,
  regions = "us",
  markets = "spreads",
  odds_format = "decimal",
  date_format = "iso"
)

Arguments

Value

A long-format tibble with one row per bookmaker market outcome:

See Also

toa_event_odds() for a single event's odds (including player props and alternate lines), toa_event_markets() to list a game's available market keys, and toa_sports() to find sport_key values. Part of the SportsDataverse.

Other The Odds API: Odds & Markets: toa_event_markets(), toa_event_odds()

Examples

try(toa_sports_odds(sport_key = 'basketball_nba',
                       regions = 'us',
                       markets = 'spreads',
                       odds_format = 'decimal',
                       date_format = 'iso'))

Description

Get historical featured-market odds for a sport which The Odds API covers.

Returns the list of events and featured bookmaker odds (h2h, spreads, totals) as they appeared at the snapshot closest to (and at or before) the requested date. The response is wrapped in a snapshot envelope; the returned timestamp, previous_timestamp and next_timestamp columns let you page backward/forward in time. This endpoint was previously ⁠/v4/sports/{sport}/odds-history⁠, which has been deprecated in favour of ⁠/v4/historical/sports/{sport}/odds⁠.

Historical data is available on paid usage plans from June 2020.

Usage quota cost: ⁠10 x [number of markets] x [number of regions]⁠. Snapshots with no events do not count against the quota.

Usage

toa_sports_odds_history(
  sport_key,
  date,
  regions = "us",
  markets = "spreads",
  odds_format = "decimal",
  date_format = "iso",
  event_ids = NULL,
  bookmakers = NULL
)

Arguments

Value

A long-format tibble with one row per bookmaker market outcome:

See Also

toa_event_odds_history() for historical odds on a single event (including player props), toa_sports_events_history() to list events at a historical snapshot, and toa_sports_odds() for current featured-market odds. Part of the SportsDataverse.

Other The Odds API: Historical: toa_event_odds_history(), toa_sports_events_history()

Examples

try(toa_sports_odds_history(sport_key = 'basketball_nba',
                               date = '2024-01-15T12:15:00Z',
                               regions = 'us',
                               markets = 'spreads',
                               odds_format = 'decimal',
                               date_format = 'iso'))

Description

Get the list of participants for a sport.

Depending on the sport a participant is either a team (e.g. NBA) or an individual (e.g. tennis). The list is a whitelist used to define events and may include participants that are no longer active. This endpoint does not return individual players on a team.

Usage quota cost: 1 credit.

Usage

toa_sports_participants(sport_key)

Arguments

Value

A tibble with one row per participant:

See Also

toa_sports() to discover sport_key values, toa_sports_events() to list upcoming events, and toa_sports_scores() for live/recent scores. Part of the SportsDataverse.

Other The Odds API: Sports & Events: toa_sports(), toa_sports_events(), toa_sports_scores()

Examples

try(toa_sports_participants(sport_key = 'basketball_nba'))

Description

Get the scores for the sports which The Odds API provides coverage.

Returns live and recently completed games for a sport, including scores for games completed within the last 3 days. Live scores update roughly every 30 seconds.

Usage quota cost: 1 credit when days_from is not supplied; 2 credits when days_from is supplied.

Usage

toa_sports_scores(sport_key, days_from = NULL, date_format = "iso")

Arguments

Value

A tibble of scores for the sport The Odds API provides coverage for:

See Also

toa_sports() to discover sport_key values, toa_sports_events() to list upcoming events, and toa_sports_odds() for live/upcoming betting lines. Part of the SportsDataverse.

Other The Odds API: Sports & Events: toa_sports(), toa_sports_events(), toa_sports_participants()

Examples

try(toa_sports_scores(sport_key = 'basketball_nba',
                         days_from = NULL,
                         date_format = 'iso'))