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
• playoff_games
• standings
• playoffs
• super_bowls
• history
• hall_of_fame
• contributors
• executives
• staff
• coaches
• assets
• all_star_games
• stats.players
• reference

Errors

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

Escape Hatch

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