nflmeta

Official Python SDK for the NFLMeta API.

Install

pip install nflmeta

Quickstart

from nflmeta import NFLMetaClient

client = NFLMetaClient(api_key="YOUR_KEY")

team = client.teams.get("PIT", season=2025)
player = client.players.identity("josh-allen-1996")
usage = client.usage.get()

print(team.data["displayName"])
print(player.data["display_name"])
print(usage.data["quota_remaining"])

What The SDK Does

• sends X-NFLMeta-Key automatically when you provide api_key
• preserves the API envelope shape: data, optional meta, plus parsed rate-limit headers
• throws typed HTTP errors for common failure cases
• exposes the main public API surfaces as resource clients instead of forcing raw URL construction
• still gives you a low-level client.get(path, query={...}) escape hatch for any route not wrapped yet

Configuration

client = NFLMetaClient(
    api_key="YOUR_KEY",
    base_url="https://nflmeta.org",
    timeout=10.0,
)

You can also pass default headers or a custom transport(url, headers, timeout) callable if you want the SDK to run through your own HTTP layer in tests or internal tooling.

Resource Coverage

The Python SDK wraps the same main surfaces as the TypeScript package:

• health
• usage
• metadata
• seasons
• teams
• players
• games
• plays
• playoff_games
• standings
• playoffs
• super_bowls
• history
• hall_of_fame
• contributors
• executives
• staff
• coaches
• assets
• all_star_games
• stats.players
• reference

client.plays.summary(season=2024, group_by="team")
client.plays.leaders(season=2024, role="passer")
client.plays.list(game_id=21390, skip_markers=True)

plays.list is metered per play and the API refuses an unnarrowed request with 400 invalid_request: pass game_id, or player, or season together with one of week, team or opponent. plays.summary and plays.leaders answer season-wide questions server-side in tens of rows.

Errors

• NFLMetaBadRequestError
• NFLMetaUnauthorizedError
• NFLMetaNotFoundError
• NFLMetaRateLimitError
• NFLMetaTimeoutError
• NFLMetaError

Escape Hatch

raw = client.get("/api/v1/reference/team-colors", query={"limit": 10})
print(raw.data)

The path is resolved against base_url and has to stay there. A URL on another origin is refused with NFLMetaInvalidUrlError before any header is built, and a redirect that would leave the origin is refused rather than followed — your API key travels in the X-NFLMeta-Key header, and urllib forwards every request header across a cross-origin redirect. Same-origin absolute URLs still work.