Python SDK

Install

pip install statapi

Quickstart

The smallest end-to-end program: construct a client, list a few rows, and print them.

# Hello, NBA
# Generated from schema/api/examples/hello-stat-api.yml — do not edit.
from statapi import StatApi
import json

api = StatApi()  # reads STAT_API_KEY from the environment

# List a few teams
teams = api.nba.teams.list(limit=3).rows

# Print what came back
print(json.dumps(teams, indent=2, default=str))

Authentication

The client reads your API key from the STAT_API_KEY environment variable — the zero-argument constructor above needs nothing else. To pass it explicitly, hand the key to the StatApi constructor. The base URL defaults to https://api.stat-api.com. Get a key on the pricing page — the free tier covers 50,000 records a month.

Pagination & iteration

Every list call returns one bounded page (default 50 rows, max 200) wrapped in the list envelope, plus a next_from_id keyset cursor. Pass it back as from_id to fetch the next page, or let the built-in auto-paging iterator, iter(), stream every row across pages for you — available on every table.

Errors

Failed requests raise a typed error rather than returning a status code: AuthenticationError (401), PlanRequiredError (402), QuotaExceededError (429), NotFoundError (404), and ValidationError (400, e.g. a missing required filter) — all subclasses of StatApiError. GET requests are retried automatically on transient network errors and 5xx responses; quota exhaustion (429) is never retried.

Quota

Every response reports your monthly usage through X-Quota-* headers, surfaced on each page (and on QuotaExceededError) as a Quota value with limit, used, and remaining record counts — the same metering as the REST API.

More

Every endpoint in the API reference carries a copy-pasteable Python call, and the examples walk through longer recipes.