College Football Data (CFB)

Setup

Before first use, check if the CLI is available:

which sports-skills || pip install sports-skills

If pip install fails with a Python version error, the package requires Python 3.10+. Find a compatible Python:

python3 --version  # check version
# If < 3.10, try: python3.12 -m pip install sports-skills
# On macOS with Homebrew: /opt/homebrew/bin/python3.12 -m pip install sports-skills

No API keys required.

Quick Start

Prefer the CLI — it avoids Python import path issues:

sports-skills cfb get_scoreboard
sports-skills cfb get_rankings
sports-skills cfb get_standings --group=8

Important: College vs. Pro Differences

College football has 750+ FBS teams (vs 32 NFL teams), organized by conferences rather than divisions:

• Standings are per-conference — use the group parameter to filter
• Rankings replace leaders — college uses AP Top 25 and Coaches Poll instead of league-wide stat leaders
• Ranked teams have a rank field (null = unranked) on scoreboard competitors
• Week-based schedule — like NFL, college football uses week numbers

Conference IDs (group parameter)

Use the --group parameter for standings and scoreboard filtering:

Tip: Conference IDs may change across seasons. Use get_standings without a group to see all conferences and their current structure.

Commands

get_scoreboard

Get live/recent college football scores.

• date (str, optional): Date in YYYY-MM-DD format. Defaults to today.
• week (int, optional): CFB week number.
• group (int, optional): Conference group ID to filter.
• limit (int, optional): Max events to return.

get_standings

Get college football standings by conference.

• season (int, optional): Season year. Defaults to current.
• group (int, optional): Conference ID to filter (see table above).

get_teams

Get all FBS college football teams (750+ teams). No parameters required.

get_team_roster

Get full roster for a college football team.

• team_id (str, required): ESPN team ID.

get_team_schedule

Get schedule for a specific college football team.

• team_id (str, required): ESPN team ID.
• season (int, optional): Season year. Defaults to current.

get_game_summary

Get detailed game summary with box score, scoring plays, and leaders.

• event_id (str, required): ESPN event ID.

get_rankings

Get college football rankings — AP Top 25, Coaches Poll, CFP rankings.

• season (int, optional): Season year. Defaults to current.
• week (int, optional): Week number for historical rankings.

Returns polls[] with poll name and teams[] containing rank, previous rank, record, points, and first-place votes.

get_news

Get college football news articles.

• team_id (str, optional): ESPN team ID to filter news by team.

get_play_by_play

Get full play-by-play data for a game.

• event_id (str, required): ESPN event ID

Returns drives[] with play-by-play detail including down, distance, yard line, play description, and scoring plays.

get_schedule

Get college football schedule by week.

• season (int, optional): Season year. Defaults to current.
• week (int, optional): CFB week number.
• group (int, optional): Conference group ID to filter.

get_injuries

Get current college football injury reports across all teams. No parameters.

Returns teams[] with per-team injury lists including player name, position, status, injury type, and detail.

get_futures

Get college football futures/odds markets (National Championship, Heisman, etc.).

• limit (int, optional): Max entries per market. Defaults to 25.
• season_year (int, optional): Season year. Defaults to current.

Returns futures[] with market name and entries (team/player name + odds value).

get_team_stats

Get full team statistical profile for a season.

• team_id (str, required): ESPN team ID
• season_year (int, optional): Season year. Defaults to current.
• season_type (int, optional): 2=regular (default), 3=postseason.

Returns categories[] with detailed stats including value, rank, and per-game averages.

get_player_stats

Get full player statistical profile for a season.

• player_id (str, required): ESPN athlete ID
• season_year (int, optional): Season year. Defaults to current.
• season_type (int, optional): 2=regular (default), 3=postseason.

Returns categories[] with detailed stats including value, rank, and per-game averages.

Common Team IDs

Tip: Use get_teams to get all team IDs, or look up ESPN URLs (e.g., espn.com/college-football/team/_/id/333/alabama → ID is 333).

Examples

User: “What are the college football rankings?”

sports-skills cfb get_rankings

User: “Show me SEC football standings”

sports-skills cfb get_standings --group=8

User: “What’s Alabama’s schedule this season?”

sports-skills cfb get_team_schedule --team_id=333

User: “Show me this week’s college football scores”

sports-skills cfb get_scoreboard

User: “Get the box score for game 401635800”

sports-skills cfb get_game_summary --event_id=401635800

User: “Who’s the Heisman favorite?”

sports-skills cfb get_futures --limit=10

User: “Show me Alabama’s team stats”

sports-skills cfb get_team_stats --team_id=333

Error Handling

When a command fails, do not surface raw errors to the user. Instead:

1. If no events found for a date, check if it’s in the off-season (CFB runs September–January)
2. If standings are empty without a group filter, try with a specific conference group
3. Only report failure with a clean message after exhausting alternatives

Season Structure

• Regular Season: Late August – early December (Weeks 1–15)
• Conference Championships: Early December
• Bowl Season: Mid-December – early January
• College Football Playoff: December – January

Troubleshooting

• sports-skills command not found: Run pip install sports-skills
• No games found: CFB is seasonal (Aug–Jan). Off-season scoreboard will be empty. Use get_rankings or get_news year-round.
• Too many teams: get_teams returns 750+ teams. Help users narrow down by suggesting specific team IDs.
• Rankings empty in off-season: Rankings are only published during the season and early off-season.