Griddy SDK Python¶

A Python SDK providing programmatic access to several American Football data sources.

Overview¶

The Griddy SDK gives you a unified interface to three major football data sources:

NFL.com API — Game schedules, box scores, play-by-play, rosters, standings, draft data, and more from the public NFL.com API
NFL Pro Stats — Advanced passing, rushing, receiving, and defensive statistics from NFL Pro
Next Gen Stats — Player tracking data, speed leaders, completion probability, and other NGS metrics
Pro Football Reference — Historical stats, player profiles, season schedules, and game details scraped from PFR

Every endpoint provides both synchronous and asynchronous methods, and all responses are validated through Pydantic models with full type annotations.

Quick Start¶

from griddy.nfl import GriddyNFL

# Initialize with an access token
nfl = GriddyNFL(nfl_auth={"accessToken": "your_token"})

# Fetch Week 1 games
games = nfl.games.get_games(
    season=2025,
    season_type="REG",
    week=1,
)

# Get passing stats for the season
passing = nfl.stats.passing.get_season_summary(
    season=2025,
    season_type="REG",
)

See the Getting Started guide for installation and authentication setup.

Guides¶

Guide	Description
Getting Started	Installation, authentication, and your first API call
NFL Regular API	Games, rosters, standings, draft, combine, and more
NFL Pro Stats	Advanced passing, rushing, receiving, and defense stats
Next Gen Stats	Player tracking data, speed leaders, and NGS metrics
Pro Football Reference	Historical stats via HTML scraping with Browserless
Authentication	Detailed auth flow: browser login vs. direct token
Error Handling	Exception hierarchy, retries, and recovery patterns
Async Usage	async/await patterns and concurrency
Architecture	Lazy-loaded sub-SDKs, hooks, and endpoint patterns
Advanced Usage	Custom hooks, request manipulation, and extending the SDK

API Reference¶

Browse the auto-generated API Reference for detailed documentation of all modules, classes, and methods.