underdog-api 0.1.0__tar.gz

underdog_api-0.1.0/.github/workflows/publish.yml

@@ -0,0 +1,22 @@
+name: Publish to PyPI
+
+on:
+  release:
+    types: [published]
+  workflow_dispatch:
+
+jobs:
+  publish:
+    runs-on: ubuntu-latest
+    environment: pypi
+    permissions:
+      id-token: write
+      contents: read
+    steps:
+      - uses: actions/checkout@v4
+      - uses: actions/setup-python@v5
+        with:
+          python-version: "3.12"
+      - run: python -m pip install --upgrade build
+      - run: python -m build
+      - uses: pypa/gh-action-pypi-publish@release/v1

underdog_api-0.1.0/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.

underdog_api-0.1.0/PKG-INFO

@@ -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/README.md

@@ -0,0 +1,84 @@
+# 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/pyproject.toml

@@ -0,0 +1,30 @@
+[build-system]
+requires = ["hatchling>=1.21"]
+build-backend = "hatchling.build"
+
+[project]
+name = "underdog-api"
+version = "0.1.0"
+description = "Python client for Underdog API: Underdog Fantasy pick'em lines, Higher/Lower multipliers, line history and graded results."
+readme = "README.md"
+requires-python = ">=3.9"
+license = { text = "MIT" }
+authors = [{ name = "Stunning Couches LLC", email = "support@underdogapi.com" }]
+keywords = ["underdog", "underdog fantasy", "pick'em", "player props", "dfs", "sports data", "api"]
+classifiers = [
+  "Programming Language :: Python :: 3",
+  "License :: OSI Approved :: MIT License",
+  "Operating System :: OS Independent",
+  "Topic :: Software Development :: Libraries",
+]
+dependencies = []
+
+[project.urls]
+Repository = "https://github.com/underdogapi/underdogapi-python"
+Issues = "https://github.com/underdogapi/underdogapi-python/issues"
+Homepage = "https://underdogapi.com"
+Documentation = "https://underdogapi.com/docs"
+Pricing = "https://underdogapi.com/pricing"
+
+[tool.hatch.build.targets.wheel]
+packages = ["src/underdog_api"]

underdog_api-0.1.0/src/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/tests/test_client.py

@@ -0,0 +1,87 @@
+import json
+import os
+import sys
+import unittest
+
+sys.path.insert(0, os.path.join(os.path.dirname(__file__), "..", "src"))
+from underdog_api import Client, PlanLimitError, UnderdogAPIError  # noqa: E402
+
+
+class Fake:
+    """Records requests and replays canned answers, so the tests never touch the network."""
+
+    def __init__(self, answers):
+        self.answers = list(answers)
+        self.calls = []
+
+    def __call__(self, method, url, headers, timeout):
+        self.calls.append((method, url, headers))
+        status, body = self.answers.pop(0)
+        return status, {"Content-Type": "application/json"}, json.dumps(body).encode()
+
+
+class ClientTest(unittest.TestCase):
+    def test_sends_bearer_key_and_filters(self):
+        fake = Fake([(200, {"data": [{"id": "udm_1"}], "meta": {"next_cursor": None}})])
+        body = Client(api_key="ud_test", transport=fake).projections(league="NBA", view="compact", limit=5)
+        self.assertEqual(body["data"][0]["id"], "udm_1")
+        method, url, headers = fake.calls[0]
+        self.assertEqual(method, "GET")
+        self.assertTrue(url.startswith("https://underdogapi.com/api/v1/projections?"))
+        self.assertIn("league=NBA", url)
+        self.assertIn("view=compact", url)
+        self.assertEqual(headers["Authorization"], "Bearer ud_test")
+
+    def test_demo_needs_no_key(self):
+        fake = Fake([(200, {"data": [], "meta": {}})])
+        Client(api_key="ud_test", transport=fake).demo("projections", league="NBA")
+        self.assertNotIn("Authorization", fake.calls[0][2])
+        self.assertIn("/api/v1/demo/projections", fake.calls[0][1])
+
+    def test_pages_follow_cursor(self):
+        fake = Fake([
+            (200, {"data": [{"id": 1}, {"id": 2}], "meta": {"next_cursor": "udm_x"}}),
+            (200, {"data": [{"id": 3}], "meta": {"next_cursor": None}}),
+        ])
+        rows = list(Client(api_key="k", transport=fake).pages("/api/v1/changes", league="NBA"))
+        self.assertEqual([r["id"] for r in rows], [1, 2, 3])
+        self.assertIn("cursor=udm_x", fake.calls[1][1])
+
+    def test_402_is_a_plan_limit_with_sample_and_link(self):
+        err = {"error": {"code": "UPGRADE_REQUIRED", "message": "Free does not include graded results.", "upgrade_url": "https://underdogapi.com/upgrade?plan=developer", "sample": [{"result": "higher"}]}}
+        fake = Fake([(402, err)])
+        with self.assertRaises(PlanLimitError) as ctx:
+            Client(api_key="k", transport=fake).results(league="NBA")
+        self.assertEqual(ctx.exception.code, "UPGRADE_REQUIRED")
+        self.assertEqual(ctx.exception.upgrade_url, "https://underdogapi.com/upgrade?plan=developer")
+        self.assertEqual(ctx.exception.sample, [{"result": "higher"}])
+
+    def test_retries_per_minute_429_but_not_monthly(self):
+        fake = Fake([(429, {"error": {"code": "RATE_LIMITED"}}), (200, {"data": [], "meta": {}})])
+        c = Client(api_key="k", transport=fake, retries=1)
+        import underdog_api
+        underdog_api.time.sleep = lambda s: None
+        c.coverage()
+        self.assertEqual(len(fake.calls), 2)
+        fake2 = Fake([(429, {"error": {"code": "MONTHLY_QUOTA_EXCEEDED", "message": "out of credits"}})])
+        with self.assertRaises(UnderdogAPIError) as ctx:
+            Client(api_key="k", transport=fake2, retries=3).coverage()
+        self.assertEqual(ctx.exception.status, 429)
+        self.assertEqual(len(fake2.calls), 1)
+
+    def test_history_path_is_quoted(self):
+        fake = Fake([(200, {"data": [], "meta": {}})])
+        Client(api_key="k", transport=fake).history("udm_00000000-0000-4000-8000-000000000001")
+        self.assertIn("/api/v1/projections/udm_00000000-0000-4000-8000-000000000001/history", fake.calls[0][1])
+
+
+@unittest.skipUnless(os.environ.get("UNDERDOG_LIVE") == "1", "set UNDERDOG_LIVE=1 to call the real keyless demo")
+class LiveDemoTest(unittest.TestCase):
+    def test_keyless_demo(self):
+        body = Client(api_key=None).demo("projections", league="NBA", limit=1)
+        self.assertTrue(body["data"])
+        self.assertIn("selections", body["data"][0])
+
+
+if __name__ == "__main__":
+    unittest.main()