Get live betting odds, spreads, and totals for NFL, NBA, MLB, and 50 additional sports and leagues. Production-ready Ruby SDK with connection pooling, 99.9% uptime, and sub-minute updates during live games. Perfect for developers building sportsbook platforms, odds comparison tools, positive EV models, and anything else that requires fast, accurate sports data.

This library provides convenient access to the Sports Game Odds REST API from any Ruby 3.2.0+ application.

The REST API documentation can be found on sportsgameodds.com. The full API of this library can be found in api.md.

For developers building the next generation of sports stats and/or betting applications:

• 📈 3k+ odds markets including moneylines, spreads, over/unders, team props, player props & more
• 🏈 50+ leagues covered including NFL, NBA, MLB, NHL, NCAAF, NCAAB, EPL, UCL, UFC, PGA, ATP & more
• 📊 80+ sportsbooks with unified odds formats, alt lines & deeplinks
• 📺 Live scores & stats coverage on all games, teams, and players
• ⚡ Sub-100ms response times and sub-minute updates for fast data
• 💎 Comprehensive Ruby type support with Yard, RBS, and RBI definitions
• 💰 Developer-friendly pricing with a generous free tier
• ⏱️ 5-minute setup with copy-paste examples

Add to your application's Gemfile:

gem "sports-odds-api", "~> 1.2.2"

Or install manually:

gem install sports-odds-api

Get a free API key from sportsgameodds.com.

Unlike enterprise-only solutions, the Sports Game Odds API offers a developer-friendly experience, transparent pricing, comprehensive documentation, and a generous free tier.

The full API of this library can be found in api.md.

require "bundler/setup"
require "sports_odds_api"

client = SportsOddsAPI::Client.new(
  api_key_param: ENV["SPORTS_ODDS_API_KEY_HEADER"] # This is the default and can be omitted
)

page = client.events.get
event = page.data[0]

puts(event.activity)

This API endpoint is only available to AllStar and custom plan subscribers. It is not included with basic subscription tiers. Contact support to get access.

This streaming API is currently in beta. API call patterns, response formats, and functionality may change. Fully managed streaming via SDK may be available in future releases.

Our Streaming API provides real-time updates for Event objects through WebSocket connections. Instead of polling our REST endpoints, you can maintain a persistent connection to receive instant notifications when events change. This is ideal for applications that need immediate updates with minimal delay.

We use Pusher Protocol for WebSocket communication. While you can connect using any WebSocket library, we recommend using the pusher-client-ruby gem.

The streaming process involves two steps:

1. Get Connection Details: Make a request using client.stream.events() to receive:

   • WebSocket authentication credentials
   • WebSocket URL/channel info
   • Initial snapshot of current data

2. Connect and Stream: Use the provided details to connect via Pusher and receive real-time eventID notifications for changed events.

Your API key will have limits on concurrent streams.

Subscribe to different feeds using the feed query parameter:

The number of supported feeds will increase over time. Please reach out if you have a use case which can't be covered by these feeds.

Here's the minimal code to connect to live events:

require "sports_odds_api"
require "pusher-client"

STREAM_FEED = "events:live" # ex: events:upcoming, events:byid, events:live
API_KEY = "YOUR API KEY"

client = SportsOddsAPI::Client.new(api_key_param: API_KEY)

# Initialize a data structure where we'll save the event data
events = {}

# Call this endpoint to get initial data and connection parameters
stream_info = client.stream.events(feed: STREAM_FEED)

# Seed initial data
stream_info.data.each { |event| events[event.eventID] = event }

# Connect to WebSocket server
pusher = PusherClient::Socket.new(stream_info.pusherKey, stream_info.pusherOptions)
channel = pusher.subscribe(stream_info.channel)

channel.bind("data") do |changed_events|
  event_ids = changed_events.map { |ev| ev["eventID"] }.join(",")

  client.events.get(eventIDs: event_ids).each do |event|
    events[event.eventID] = event
  end
end

trap("SIGINT") { pusher.disconnect }
pusher.connect

List methods in the Sports Game Odds API are paginated.

This library provides auto-paginating iterators with each list response:

page = client.events.get(limit: 30)

page.auto_paging_each do |event|
  puts(event.activity)
end

Or, you can use #next_page? and #next_page for manual pagination.

When the library is unable to connect to the API, or if the API returns a non-success status code (4xx or 5xx), a subclass of SportsOddsAPI::Errors::APIError will be thrown.

begin
  page = client.events.get
rescue SportsOddsAPI::Errors::APIError => e
  puts(e.message)
end

Error codes map to specific exception classes, such as AuthenticationError, RateLimitError, NotFoundError, etc.

Certain errors are retried automatically with exponential backoff. Configure retries globally or per-request with the max_retries option.

Requests time out after 60 seconds by default. Configure with timeout globally or per-request.

• Access undocumented params via extra_query, extra_body, and extra_headers
• Use client.request for undocumented endpoints
• Threadsafe client with connection pooling
• Sorbet integration via RBI & RBS definitions

• Ruby 3.2.0+

See the contributing documentation.