Package 'oddsapi'

oddsapi: R client for odds-api.net

Description

Fetch sports betting odds, events, bookmaker catalogs, results and racing data from Odds API. Start with odds_client() and odds_events(), then convert a sports odds_snapshot() with odds_table().

Author(s)

Maintainer: Odds API [email protected]

Authors:

• Odds API [email protected]

See Also

https://odds-api.net, https://github.com/odds-api/odds-api, https://api.odds-api.net/v1/reference

---

Create an odds-api.net client

Description

Connect to the sports odds API at https://odds-api.net. Credentials are sent in a redacted X-API-Key header, never in the query string.

Usage

odds_client(
  api_key = Sys.getenv("ODDS_API_KEY"),
  base_url = Sys.getenv("ODDS_API_BASE_URL", "https://api.odds-api.net/v1"),
  timeout = 30,
  max_tries = 3L
)

Arguments

api_key	API key. Defaults to ODDS_API_KEY. An empty string allows access to public endpoints such as ⁠/status⁠.
base_url	API base URL. Defaults to ODDS_API_BASE_URL, or ⁠https://api.odds-api.net/v1⁠. HTTPS is required except on loopback hosts.
timeout	Request timeout in seconds; a positive finite number.
max_tries	Maximum total attempts per request, from 1 to 10. Retries apply to HTTP 429, 502, 503 and 504, and connection failures.

Value

An odds_api_client object. Printing it hides the API key.

Examples

client <- odds_client(api_key = "")
client

---

Collect every page from a cursor endpoint

Description

Pagination is explicit because each page is a separate API request and may consume credits. A repeated cursor or exhausted page budget raises an error instead of silently returning incomplete results. An empty page with a nonterminal cursor is followed, as required for odds snapshot scans.

Usage

odds_collect(client, path, ..., max_pages = 100L)

Arguments

client	A client created by odds_client().
path	Cursor endpoint: ⁠/events⁠, ⁠/racing/events⁠, or a sports event's ⁠/events/{event_id}/odds/snapshot⁠ path.
...	Named query filters, optionally including a starting cursor.
max_pages	Positive integer limit on requests (default 100).

Value

A list containing items, count, pages and next_cursor = NULL. Use odds_snapshot() for the original snapshot freshness/resume metadata; collected pages do not represent an atomic snapshot.

Examples

## Not run: 
events <- odds_collect(odds_client(), "/events", league = "NBA", max_pages = 5)

## End(Not run)

---

Read sports, odds, results and account data

Description

Thin wrappers around the public odds-api.net API. Responses remain nested lists; use odds_table() for a sports odds data frame. Each call requests one page. Use odds_collect() when the endpoint supports next_cursor. Consult https://api.odds-api.net/v1/reference for filters.

Usage

odds_sports(client)

odds_leagues(client, ...)

odds_bookmakers(client, ...)

odds_events(client, ...)

odds_event(client, event_id, ...)

odds_event_bookmakers(client, event_id)

odds_snapshot(client, event_id, ...)

odds_history(client, event_id, selection_key, ...)

odds_results(client, event_id)

odds_bets(client, ...)

odds_racing_events(client, ...)

odds_racing_event(client, event_id, ...)

odds_racing_snapshot(client, event_id, ...)

odds_me(client)

odds_usage(client)

odds_limits(client)

odds_status(client)

Arguments

client	A client created by odds_client().
...	Named API query filters, forwarded to odds_get().
event_id	Canonical event identifier, as returned by odds_events() or odds_racing_events().
selection_key	Stable selection identifier returned by an odds snapshot.

Value

Parsed JSON as nested R lists, including any pagination metadata.

Examples

## Not run: 
client <- odds_client()
odds_sports(client)
odds_bookmakers(client, country_code = c("US", "AU"))
events <- odds_events(client, sport = "basketball", league = "NBA", limit = 10)
if (length(events$items)) {
  id <- events$items[[1]]$event_id
  snapshot <- odds_snapshot(client, id, types = "moneyline")
  odds_table(snapshot)
}

## End(Not run)

---

Request a public API endpoint

Description

Returns JSON as nested R lists, preserving pagination and snapshot metadata. Only GET requests are made. See the public API contract at https://api.odds-api.net/v1/reference for filters and response fields.

Usage

odds_get(client, path, ...)

Arguments

client	A client created by odds_client().
path	API-relative path, for example ⁠/events⁠.
...	Named query parameters. Vectors become comma-separated filters, logical values become true/false, and NULL values are omitted.

Value

Parsed JSON, usually a list. HTTP 204 returns NULL. Failures raise odds_api_error with status (or NA for transport failures) and retry_after fields. Error messages do not echo credentials or server bodies.

Examples

## Not run: 
client <- odds_client()
odds_get(client, "/events", sport = "basketball", league = "NBA", limit = 10)

## End(Not run)

---

Convert a sports odds snapshot to a data frame

Description

Preserves selection identifiers, decimal odds, missing values and line text. No prices are inferred and unavailable selections remain visible. This helper accepts sports odds, not the nested racing bookmaker/runner format.

Usage

odds_table(snapshot)

Arguments

snapshot

A response from odds_snapshot() or odds_collect() for a sports odds endpoint, containing an items list.

Value

A data frame with one row per odds record, stable column types and NA for absent values. as_of_ts_ms and ttl_seconds are attributes copied from a single-page snapshot, when present. Empty responses retain columns.

Examples

fixture <- system.file("extdata", "odds-snapshot.json", package = "oddsapi")
# The bundled fixture is synthetic and needs no API key.
snapshot <- httr2::resp_body_json(httr2::response(
  status_code = 200, headers = list(`content-type` = "application/json"),
  body = readBin(fixture, "raw", n = file.info(fixture)$size)))
odds_table(snapshot)

---