From 5d7f6bf4c6da356f1fae76a1e8137e6914f4469d Mon Sep 17 00:00:00 2001 From: odds-api-io Date: Fri, 6 Nov 2026 15:41:48 +0100 Subject: [PATCH] fix: document expectedValue as bookmaker/fair x 100, bump to 1.2.1 expectedValue is bookmaker odds / fair odds x 100 (103.42 = 3.42% edge), not a fraction. Fixes the value_bets example, the ValueBet and get_value_bets docstrings and the README snippet. --- CHANGELOG.md | 5 +++++ CITATION.cff | 2 +- README.md | 5 ++++- examples/value_bets.py | 7 +++++-- odds_api/__init__.py | 2 +- odds_api/async_client.py | 3 +++ odds_api/client.py | 3 +++ odds_api/types.py | 6 ++++++ pyproject.toml | 2 +- 9 files changed, 29 insertions(+), 6 deletions(-) diff --git a/CHANGELOG.md b/CHANGELOG.md index 064818c..b894629 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -1,5 +1,10 @@ # Changelog +## 1.2.1 (2026-11-06) + +### Fixed +- Docs: `expectedValue` on value bets is bookmaker odds / fair odds x 100, not a fraction. 103.42 is a 3.42% edge (edge % = `expectedValue - 100`). The `ValueBet` docstring, `get_value_bets` docstrings, README and `examples/value_bets.py` now say so; the example prints and filters on `expectedValue - 100`. + ## 1.2.0 (2026-11-06) Brings the SDK up to the full Odds-API.io v3 API. diff --git a/CITATION.cff b/CITATION.cff index b5a132f..558b748 100644 --- a/CITATION.cff +++ b/CITATION.cff @@ -1,4 +1,4 @@ -cff-version: 1.2.0 +cff-version: 1.2.1 message: "If you use this software, please cite it using the metadata from this file." type: software title: "odds-api-io: Official Python SDK for Odds-API.io" diff --git a/README.md b/README.md index b43e1d1..7559ddd 100644 --- a/README.md +++ b/README.md @@ -116,7 +116,10 @@ arbs = client.get_arbitrage_bets( ["Bet365", "SingBet"], sport="football", markets=["ML", "Totals"], min_profit=1.0, include_event_details=True, ) +# profitMargin is already a percentage (2.48 means 2.48%) value = client.get_value_bets("Bet365", sport="baseball", league="usa-mlb") +# expectedValue is bookmaker odds / fair odds x 100, so 103.42 is a 3.42% edge +edges = [b for b in value if b["expectedValue"] - 100 >= 3] drops = client.get_dropping_odds(sport="football", markets=["Spread"], time_window="24h", min_drop=10) ``` @@ -276,5 +279,5 @@ MIT. See [LICENSE](LICENSE). If you use this package in research or a publication, please cite it. Citation metadata is in [CITATION.cff](CITATION.cff) (GitHub renders a "Cite this repository" button from it) and Zenodo metadata is in `.zenodo.json`. ``` -Outlier AS. odds-api-io: Official Python SDK for Odds-API.io (version 1.2.0). https://github.com/odds-api-io/odds-api-python +Outlier AS. odds-api-io: Official Python SDK for Odds-API.io (version 1.2.1). https://github.com/odds-api-io/odds-api-python ``` diff --git a/examples/value_bets.py b/examples/value_bets.py index 3976856..fff48bb 100644 --- a/examples/value_bets.py +++ b/examples/value_bets.py @@ -1,7 +1,8 @@ """ Find prices above a fair-odds estimate at one bookmaker. -expectedValue is a fraction: 0.0523 means +5.23% expected value at that price. +expectedValue is bookmaker odds / fair odds x 100: 103.42 means a 3.42% edge at that price. +The edge in percent is expectedValue - 100; values below 100 are a negative edge. """ import os @@ -10,12 +11,14 @@ # Get an API key at https://odds-api.io/pricing API_KEY = os.getenv("ODDS_API_KEY", "your_api_key_here") +MIN_EDGE_PERCENT = 2 def main(): with OddsAPIClient(api_key=API_KEY) as client: bets = client.get_value_bets("Bet365", sport="football", include_event_details=True) bets = sorted(bets, key=lambda b: b["expectedValue"], reverse=True) + bets = [b for b in bets if b["expectedValue"] - 100 >= MIN_EDGE_PERCENT] if not bets: print("No value bets at the moment.") return @@ -28,7 +31,7 @@ def main(): print(f"{event.get('home')} vs {event.get('away')} ({event.get('date')})") print( f" {market['name']}{line} {bet['betSide']} @ {price}: " - f"EV {bet['expectedValue'] * 100:+.2f}%" + f"edge {bet['expectedValue'] - 100:+.2f}%" ) diff --git a/odds_api/__init__.py b/odds_api/__init__.py index 976cb1a..4bceeb8 100644 --- a/odds_api/__init__.py +++ b/odds_api/__init__.py @@ -3,7 +3,7 @@ Official Python client for the Odds-API.io sports betting odds API. """ -__version__ = "1.2.0" +__version__ = "1.2.1" from .client import OddsAPIClient from .async_client import AsyncOddsAPIClient diff --git a/odds_api/async_client.py b/odds_api/async_client.py index 30e714a..442ffb0 100644 --- a/odds_api/async_client.py +++ b/odds_api/async_client.py @@ -705,6 +705,9 @@ async def get_value_bets( """ Get prices above a fair-odds estimate at one bookmaker. + ``expectedValue`` in each result is bookmaker odds / fair odds x 100, so + 103.42 is a 3.42% edge. Edge in percent = ``expectedValue - 100``. + Args: bookmaker: Bookmaker name include_event_details: Include teams, date, sport and league diff --git a/odds_api/client.py b/odds_api/client.py index 5ac2fc3..2e4a6e4 100644 --- a/odds_api/client.py +++ b/odds_api/client.py @@ -697,6 +697,9 @@ def get_value_bets( """ Get prices above a fair-odds estimate at one bookmaker. + ``expectedValue`` in each result is bookmaker odds / fair odds x 100, so + 103.42 is a 3.42% edge. Edge in percent = ``expectedValue - 100``. + Args: bookmaker: Bookmaker name include_event_details: Include teams, date, sport and league diff --git a/odds_api/types.py b/odds_api/types.py index a406738..ea89e1f 100644 --- a/odds_api/types.py +++ b/odds_api/types.py @@ -189,6 +189,12 @@ class OddsSummary(TypedDict, total=False): class ValueBet(TypedDict, total=False): + """A price above the fair-odds estimate. + + ``expectedValue`` is bookmaker odds / fair odds x 100: 100 is fair, 103.42 is a + 3.42% edge (edge % = ``expectedValue - 100``), below 100 is a negative edge. + """ + id: str eventId: int bookmaker: str diff --git a/pyproject.toml b/pyproject.toml index e4264ec..9f010f0 100644 --- a/pyproject.toml +++ b/pyproject.toml @@ -4,7 +4,7 @@ build-backend = "setuptools.build_meta" [project] name = "odds-api-io" -version = "1.2.0" +version = "1.2.1" description = "Official Python SDK for Odds-API.io, the sports betting odds API: live and pre-match odds from 450+ bookmakers across 34 sports, player props, golf outrights, closing lines, settlement, arbitrage, value bets and WebSocket" readme = "README.md" requires-python = ">=3.8"