underdog-api 0.1.0__py3-none-any.whl

underdog_api/__init__.py

@@ -0,0 +1,184 @@
+"""Python client for Underdog API (https://underdogapi.com).
+
+Underdog API is an independent REST API for Underdog Fantasy pick'em lines: separate Higher and Lower payout
+multipliers, every recorded line move and graded results. It is operated by Stunning Couches LLC and is not
+affiliated with Underdog Fantasy.
+
+    from underdog_api import Client
+    ud = Client()                      # reads UNDERDOG_API_KEY
+    for line in ud.projections(league="NBA", view="compact", limit=5)["data"]:
+        print(line)
+
+No dependencies: the standard library only.
+"""
+from __future__ import annotations
+
+import json
+import os
+import time
+import urllib.error
+import urllib.parse
+import urllib.request
+from typing import Any, Callable, Dict, Iterator, Optional
+
+__all__ = ["Client", "UnderdogAPIError", "PlanLimitError", "__version__"]
+__version__ = "0.1.0"
+
+DEFAULT_BASE_URL = "https://underdogapi.com"
+Transport = Callable[[str, str, Dict[str, str], float], "tuple[int, Dict[str, str], bytes]"]
+
+
+class UnderdogAPIError(Exception):
+    """A non-2xx answer. `code`, `message` and the full `body` come from the API's error object."""
+
+    def __init__(self, status: int, body: Any, headers: Optional[Dict[str, str]] = None):
+        err = body.get("error", {}) if isinstance(body, dict) else {}
+        self.status = status
+        self.body = body
+        self.headers = headers or {}
+        self.code = err.get("code")
+        self.message = err.get("message") or (body if isinstance(body, str) else "") or f"HTTP {status}"
+        super().__init__(f"{status} {self.code or ''} {self.message}".strip())
+
+
+class PlanLimitError(UnderdogAPIError):
+    """402 UPGRADE_REQUIRED: the plan does not include this. No credits were charged.
+
+    `upgrade_url` is a checkout link and `sample` holds a few labelled rows of what was asked for.
+    """
+
+    @property
+    def upgrade_url(self) -> Optional[str]:
+        return (self.body.get("error") or {}).get("upgrade_url") if isinstance(self.body, dict) else None
+
+    @property
+    def sample(self) -> list:
+        return (self.body.get("error") or {}).get("sample") or [] if isinstance(self.body, dict) else []
+
+
+def _urllib_transport(method: str, url: str, headers: Dict[str, str], timeout: float):
+    req = urllib.request.Request(url, method=method, headers=headers)
+    try:
+        with urllib.request.urlopen(req, timeout=timeout) as res:
+            return res.status, dict(res.headers.items()), res.read()
+    except urllib.error.HTTPError as e:
+        return e.code, dict(e.headers.items()) if e.headers else {}, e.read()
+
+
+class Client:
+    """One API key, one base URL. Every method returns the parsed JSON body: {"data": [...], "meta": {...}}."""
+
+    def __init__(
+        self,
+        api_key: Optional[str] = None,
+        base_url: str = DEFAULT_BASE_URL,
+        timeout: float = 30.0,
+        retries: int = 2,
+        transport: Optional[Transport] = None,
+        user_agent: str = f"underdog-api-python/{__version__}",
+    ):
+        self.api_key = api_key if api_key is not None else os.environ.get("UNDERDOG_API_KEY")
+        self.base_url = base_url.rstrip("/")
+        self.timeout = timeout
+        self.retries = retries
+        self._transport = transport or _urllib_transport
+        self.user_agent = user_agent
+
+    # -- plumbing ---------------------------------------------------------------------------------------------
+    def get(self, path: str, **params: Any) -> Any:
+        """GET any documented path, for example client.get("/api/v1/coverage")."""
+        query = {k: ("true" if v is True else "false" if v is False else v) for k, v in params.items() if v is not None}
+        url = f"{self.base_url}{path}" + (f"?{urllib.parse.urlencode(query)}" if query else "")
+        headers = {"Accept": "application/json", "User-Agent": self.user_agent}
+        if self.api_key and not path.startswith("/api/v1/demo/"):
+            headers["Authorization"] = f"Bearer {self.api_key}"
+        attempt = 0
+        while True:
+            status, res_headers, raw = self._transport("GET", url, headers, self.timeout)
+            text = raw.decode("utf-8", "replace") if isinstance(raw, (bytes, bytearray)) else str(raw)
+            try:
+                body: Any = json.loads(text) if text else None
+            except ValueError:
+                body = text
+            if 200 <= status < 300 or status == 304:
+                return body
+            retry_after = _header(res_headers, "retry-after")
+            # Per-minute 429s and 5xx are retried; the monthly 429 (credits used up) is not.
+            monthly = isinstance(body, dict) and (body.get("error") or {}).get("code") == "MONTHLY_QUOTA_EXCEEDED"
+            if attempt < self.retries and (status >= 500 or (status == 429 and not monthly)):
+                attempt += 1
+                time.sleep(min(float(retry_after) if retry_after and retry_after.isdigit() else 2 ** attempt, 30))
+                continue
+            if status == 402:
+                raise PlanLimitError(status, body, res_headers)
+            raise UnderdogAPIError(status, body, res_headers)
+
+    def pages(self, path: str, **params: Any) -> Iterator[Dict[str, Any]]:
+        """Yield rows across pages, following meta.next_cursor with the same filters."""
+        cursor = params.pop("cursor", None)
+        while True:
+            body = self.get(path, cursor=cursor, **params)
+            for row in body.get("data") or []:
+                yield row
+            cursor = (body.get("meta") or {}).get("next_cursor")
+            if not cursor:
+                return
+
+    # -- endpoints --------------------------------------------------------------------------------------------
+    def coverage(self, **p: Any) -> Any:
+        """Leagues, stats and the first recorded date per league."""
+        return self.get("/api/v1/coverage", **p)
+
+    def projections(self, league: Optional[str] = None, **p: Any) -> Any:
+        """The current board. Filters: league, stat, search, payout_tier, status, view=compact, limit, cursor."""
+        return self.get("/api/v1/projections", league=league, **p)
+
+    def odds(self, league: Optional[str] = None, **p: Any) -> Any:
+        """Each line with its Higher and Lower side as odds entries (5 minutes behind on Free)."""
+        return self.get("/api/v1/odds", league=league, **p)
+
+    def history(self, projection_id: str, **p: Any) -> Any:
+        """Every recorded change of one market."""
+        return self.get(f"/api/v1/projections/{urllib.parse.quote(projection_id)}/history", **p)
+
+    def changes(self, league: Optional[str] = None, **p: Any) -> Any:
+        """The change feed: event_type, since, cursor, limit."""
+        return self.get("/api/v1/changes", league=league, **p)
+
+    def board(self, as_of: str, league: Optional[str] = None, **p: Any) -> Any:
+        """The board as it stood at as_of (ISO timestamp)."""
+        return self.get("/api/v1/board", as_of=as_of, league=league, **p)
+
+    def results(self, league: Optional[str] = None, **p: Any) -> Any:
+        """Graded lines: player, stat, date (US Eastern), result. Paid plans; Free raises PlanLimitError."""
+        return self.get("/api/v1/results", league=league, **p)
+
+    def hit_rates(self, player: str, **p: Any) -> Any:
+        """How often a player went Higher or Lower over graded games: stat, league, last."""
+        return self.get("/api/v1/hit-rates", player=player, **p)
+
+    def training_set(self, league: Optional[str] = None, **p: Any) -> Any:
+        """One labelled row per graded line, for model training. Paid plans."""
+        return self.get("/api/v1/training-set", league=league, **p)
+
+    def multipliers(self, league: Optional[str] = None, **p: Any) -> Any:
+        return self.get("/api/v1/multipliers", league=league, **p)
+
+    def payouts(self) -> Any:
+        """Standard, Flex and Streaks payout reference."""
+        return self.get("/api/v1/payouts")
+
+    def credit_costs(self, path: Optional[str] = None) -> Any:
+        """The credit policy, or the quote for one request path. No key needed."""
+        return self.get("/api/v1/credit-costs", path=path)
+
+    def demo(self, resource: str = "projections", **p: Any) -> Any:
+        """Fictional rows in the live shape, no key: projections, changes, coverage, export, payouts."""
+        return self.get(f"/api/v1/demo/{resource}", **p)
+
+
+def _header(headers: Dict[str, str], name: str) -> Optional[str]:
+    for k, v in (headers or {}).items():
+        if k.lower() == name:
+            return v
+    return None

underdog_api-0.1.0.dist-info/METADATA

@@ -0,0 +1,104 @@
+Metadata-Version: 2.5
+Name: underdog-api
+Version: 0.1.0
+Summary: Python client for Underdog API: Underdog Fantasy pick'em lines, Higher/Lower multipliers, line history and graded results.
+Project-URL: Repository, https://github.com/underdogapi/underdogapi-python
+Project-URL: Issues, https://github.com/underdogapi/underdogapi-python/issues
+Project-URL: Homepage, https://underdogapi.com
+Project-URL: Documentation, https://underdogapi.com/docs
+Project-URL: Pricing, https://underdogapi.com/pricing
+Author-email: Stunning Couches LLC <support@underdogapi.com>
+License: MIT
+License-File: LICENSE
+Keywords: api,dfs,pick'em,player props,sports data,underdog,underdog fantasy
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Operating System :: OS Independent
+Classifier: Programming Language :: Python :: 3
+Classifier: Topic :: Software Development :: Libraries
+Requires-Python: >=3.9
+Description-Content-Type: text/markdown
+
+# underdog-api (Python)
+
+Python client for [Underdog API](https://underdogapi.com): Underdog Fantasy pick'em lines with separate Higher and
+Lower payout multipliers, every recorded line move since 6 Nov 2026, the board at any past instant, and graded results.
+Standard library only; Python 3.9+.
+
+Underdog API is an independent data service operated by Stunning Couches LLC. It is not affiliated with, endorsed by
+or operated by Underdog Fantasy.
+
+## Install
+
+```bash
+pip install underdog-api
+export UNDERDOG_API_KEY=ud_...   # free key, no card: https://underdogapi.com/sign-up
+```
+
+## Try it without a key
+
+```python
+from underdog_api import Client
+
+demo = Client(api_key=None).demo("projections", league="NBA", limit=1)
+print(demo["data"][0]["player"]["name"], demo["data"][0]["selections"])   # fictional rows, live shape
+```
+
+## The current board
+
+```python
+from underdog_api import Client
+
+ud = Client()  # reads UNDERDOG_API_KEY
+board = ud.projections(league="NBA", view="compact", limit=20)
+for line in board["data"]:
+    print(line)
+print(board["meta"]["observed_at"])
+```
+
+## Everything that moved
+
+```python
+for change in ud.pages("/api/v1/changes", league="NFL", event_type="line.moved", limit=200):
+    print(change["observed_at"], change["player_name"], change["stat"], change["previous_line"], "->", change["line"])
+```
+
+## The board at a past moment, and graded results (paid plans)
+
+```python
+past = ud.board(as_of="2026-11-14T23:00:00Z", league="NHL", limit=100)
+graded = ud.results(league="NBA", date="2026-11-13", limit=200)
+```
+
+On the free key, graded results, hit rates, game logs, exports and the training set raise `PlanLimitError` with a
+few labelled sample rows and the upgrade link; no credits are charged:
+
+```python
+from underdog_api import PlanLimitError
+
+try:
+    ud.results(league="NBA")
+except PlanLimitError as e:
+    print(e.message, e.upgrade_url, e.sample[:2])
+```
+
+## Into pandas
+
+```python
+import pandas as pd
+rows = list(ud.pages("/api/v1/projections", league="NBA", view="compact", limit=200))
+df = pd.json_normalize(rows)
+```
+
+## Notes
+
+- Every method returns the parsed JSON body (`data` and `meta`). `ud.get(path, **params)` reaches any documented path.
+- Per-minute 429s and 5xx answers are retried with backoff; the monthly credit 429 is raised at once.
+- Credits: one per started 100 rows on simple reads; `ud.credit_costs()` returns the policy with no key.
+- Reference: https://underdogapi.com/docs · Plans: https://underdogapi.com/pricing
+
+## Tests
+
+```bash
+python -m unittest discover -s tests          # offline, fake transport
+UNDERDOG_LIVE=1 python -m unittest discover -s tests   # also calls the keyless demo
+```

underdog_api-0.1.0.dist-info/RECORD

@@ -0,0 +1,5 @@
+underdog_api/__init__.py,sha256=t46FhU4r12x69y691OKgNo3RBRXZ4FmmOijiBBO4Bos,8524
+underdog_api-0.1.0.dist-info/METADATA,sha256=cD6Qqr8baC-QqJWa_qCm6Gua5m9g32iDmtL5T9DHtFE,3607
+underdog_api-0.1.0.dist-info/WHEEL,sha256=2iZrJkDIkeDh0k9SikKMqFuRP-ua6mb4Ir1AsER4BEw,87
+underdog_api-0.1.0.dist-info/licenses/LICENSE,sha256=fPaBah2bETIgfvPKPxdsnSYOM8etWW_uvYwTiwARegk,1077
+underdog_api-0.1.0.dist-info/RECORD,,

underdog_api-0.1.0.dist-info/WHEEL

@@ -0,0 +1,4 @@
+Wheel-Version: 1.0
+Generator: hatchling 1.33.0
+Root-Is-Purelib: true
+Tag: py3-none-any

underdog_api-0.1.0.dist-info/licenses/LICENSE

@@ -0,0 +1,16 @@
+MIT License
+
+Copyright (c) 2026 Stunning Couches LLC
+
+Permission is hereby granted, free of charge, to any person obtaining a copy of this software and associated
+documentation files (the "Software"), to deal in the Software without restriction, including without limitation the
+rights to use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies of the Software, and to permit
+persons to whom the Software is furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all copies or substantial portions of the
+Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE
+WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR
+COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR
+OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.