Skip to content

Getting Started

This guide walks you through installing the Griddy SDK, authenticating, and making your first API calls.

Installation

Install the SDK with pip:

pip install griddy

Or with uv:

uv add griddy

Browser Authentication Extra

If you want to authenticate via automated browser login (Playwright), install with the browser-auth extra:

pip install "griddy[browser-auth]"

This installs Playwright and its browser binaries. After installing, run:

playwright install chromium

Authentication

The NFL.com API requires an access token. The Griddy SDK supports two authentication methods.

Method 1: Direct Token

If you already have an NFL.com access token (e.g., from a browser session), pass it directly:

from griddy.nfl import GriddyNFL

nfl = GriddyNFL(nfl_auth={"accessToken": "your_access_token"})

You can also provide a refresh token and expiration for automatic token renewal:

nfl = GriddyNFL(
    nfl_auth={
        "accessToken": "your_access_token",
        "refreshToken": "your_refresh_token",
        "expiresIn": 1735689600,  # Unix timestamp
    }
)

When a refresh token is provided, the SDK automatically refreshes the access token before it expires.

Method 2: Browser Authentication

Automate the login flow using Playwright:

from griddy.nfl import GriddyNFL

nfl = GriddyNFL.authenticate_via_browser(
    login_email="[email protected]",
    login_password="your_password",
    headless=True,
    save_credentials_path="credentials.json",
)

This opens a headless browser, logs in to NFL.com, captures the auth tokens, and optionally saves them to a file for reuse.

Environment Variables

Store credentials as environment variables to avoid hardcoding them:

export NFL_LOGIN_EMAIL="[email protected]"
export NFL_LOGIN_PASSWORD="your_password"

import os
from griddy.nfl import GriddyNFL

nfl = GriddyNFL.authenticate_via_browser(
    login_email=os.environ["NFL_LOGIN_EMAIL"],
    login_password=os.environ["NFL_LOGIN_PASSWORD"],
    headless=True,
)

See the Authentication Guide for more details on token refresh, credential persistence, and environment variable configuration.

Your First API Call

Once authenticated, access NFL data through the SDK's sub-SDKs:

from griddy.nfl import GriddyNFL

nfl = GriddyNFL(nfl_auth={"accessToken": "your_token"})

# Get scheduled games for Week 1 of the 2025 regular season
games = nfl.games.get_games(
    season=2025,
    season_type="REG",
    week=1,
)

# Iterate over the results
for game in games:
    print(f"{game.away_team} @ {game.home_team}")

Fetching Pro Stats

Advanced stats live under nfl.stats:

# Season passing leaders
passing = nfl.stats.passing.get_season_summary(
    season=2025,
    season_type="REG",
    qualified_passer=True,
)

Using Pro Football Reference

The PFR client scrapes Pro Football Reference for historical data:

from griddy.pfr import GriddyPFR

pfr = GriddyPFR()

# Get the 2024 season schedule
schedule = pfr.schedule.get_season_schedule(season=2024)

# Get a specific game's box score
game = pfr.games.get_game_details(game_id="202502090kan")

Note

The PFR client requires a Browserless instance for rendering JavaScript-heavy pages. See the PFR Guide for setup instructions.

Context Manager Support

All SDK clients support the context manager protocol for resource cleanup:

with GriddyNFL(nfl_auth={"accessToken": "your_token"}) as nfl:
    games = nfl.games.get_games(season=2025, season_type="REG", week=1)
# HTTP client resources are cleaned up automatically

Next Steps