kingsplaybook 0.1.0

Official Python SDK for the KingsPlaybook Developer API — confirmed lineups, player projections, canonical lines, and pick-history archive for NBA, MLB, and NHL.

kingsplaybook

The official Python SDK for the KingsPlaybook Developer API — confirmed lineups, raw player projections, canonical game lines, and a pick-history archive for NBA, MLB, and NHL.

It's a thin, typed wrapper over the public /v1 REST API: one client class, one method per endpoint. Zero dependencies — it uses only the Python standard library.

Install

pip install kingsplaybook

Requires Python 3.9+.

Get an API key

Sign up at kingsplaybook.org/devs. Your key looks like kp_live_…. The Free tier covers lineups; paid tiers add projections, lines, and history.

Quick start

from kingsplaybook import KingsPlaybook

kp = KingsPlaybook(api_key="kp_live_...")

# Confirmed lineups (Free tier)
lineups = kp.lineups(league="nba", date="2026-05-21")
for game in lineups["data"]:
    away = (game["away_team"] or {}).get("abbreviation")
    home = (game["home_team"] or {}).get("abbreviation")
    print(f"{away} @ {home}")

# Player projections (Starter tier and up)
projections = kp.projections(league="nba", date="2026-05-21")
print(f"{projections['meta']['count']} projections")

The api_key argument falls back to the KINGSPLAYBOOK_API_KEY environment variable, so KingsPlaybook() works when that is set.

Methods

Method	Endpoint	Min. tier
kp.health()	GET /v1/health	none
kp.freshness()	GET /v1/meta/freshness	Free
kp.lineups(league, date)	GET /v1/lineups	Free
kp.projections(league, date)	GET /v1/projections	Starter
kp.lines(league, date)	GET /v1/lines	Pro
kp.history(date, pick_type=…, sport=…)	GET /v1/history/picks	Premium

league is "nba", "mlb", or "nhl". date is an ISO-8601 string (YYYY-MM-DD). For history, pick_type is "game" or "prop" (omit for both).

Each method returns a plain dict shaped {"data": ..., "meta": ...}. The package ships TypedDict definitions (LineupsResponse, ProjectionsResponse, …) in kingsplaybook.models, and is marked py.typed — type checkers and editors get full autocomplete over the responses.

Error handling

Every failure raises a KingsPlaybookError or a subclass. The subclass tells you what went wrong without parsing a message:

from kingsplaybook import (
    KingsPlaybook,
    AuthenticationError,
    TierError,
    RateLimitError,
    KingsPlaybookError,
)

try:
    kp.lines(league="mlb", date="2026-05-21")
except AuthenticationError:
    ...  # 401 — key missing, invalid, or revoked
except TierError:
    ...  # 403 — your plan does not include this endpoint
except RateLimitError:
    ...  # 429 — back off and retry
except KingsPlaybookError as exc:
    ...  # anything else (transport, 404, 5xx) — exc.status has the code

Configuration

KingsPlaybook(
    api_key="kp_live_...",   # or KINGSPLAYBOOK_API_KEY
    base_url="https://api.kingsplaybook.org",  # or KINGSPLAYBOOK_API_URL
    timeout=30.0,            # per-request timeout, seconds
)

License

MIT