@lap v0.3
# Machine-readable API spec. Each @endpoint block is one API call.
@api College Football Data API
@base https://api.collegefootballdata.com/
@version 5.13.2
@auth Bearer bearer
@endpoints 60
@hint download_for_search
@toc wepa(4), teams(4), roster(1), conferences(1), talent(1), venues(1), stats(6), recruiting(3), ratings(5), rankings(1), plays(4), player(4), ppa(5), metrics(3), live(1), lines(1), info(1), games(5), records(1), calendar(1), scoreboard(1), drives(1), draft(3), coaches(1), game(1)

@group wepa
@endpoint GET /wepa/team/season
@desc Retrieve opponent-adjusted team season statistics
@optional {year: int(int32) # Optional year filter, team: str # Optional team filter, conference: str # Optional conference filter}
@returns(200) Ok

@endpoint GET /wepa/players/passing
@desc Retrieve opponent-adjusted player passing statistics
@optional {year: int(int32) # Optional year filter, team: str # Optional team filter, conference: str # Optional conference abbreviation filter, position: str # Optional position abbreviation filter}
@returns(200) Ok

@endpoint GET /wepa/players/rushing
@desc Retrieve opponent-adjusted player rushing statistics
@optional {year: int(int32) # Optional year filter, team: str # Optional team filter, conference: str # Optional conference abbreviation filter, position: str # Optional position abbreviation filter}
@returns(200) Ok

@endpoint GET /wepa/players/kicking
@desc Retrieve Points Added Above Replacement (PAAR) ratings for kickers
@optional {year: int(int32) # Optional year filter, team: str # Optional team filter, conference: str # Optional conference abbreviation filter}
@returns(200) Ok

@endgroup

@group teams
@endpoint GET /teams
@desc Retrieves team information
@optional {conference: str # Optional conference abbreviation filter, year: int(int32) # Optional year filter to get historical conference affiliations}
@returns(200) Ok

@endpoint GET /teams/fbs
@desc Retrieves information on teams playing in the highest division of CFB
@optional {year: int(int32) # Year or season}
@returns(200) Ok

@endpoint GET /teams/matchup
@desc Retrieves historical matchup details for two given teams
@required {team1: str # First team to compare, team2: str # Second team to compare}
@optional {minYear: int(int32) # Optional starting year, maxYear: int(int32) # Optional ending year}
@returns(200) {team1: str, team2: str, startYear: int(int32), endYear: int(int32), team1Wins: int(int32), team2Wins: int(int32), ties: int(int32), games: [map]} # Ok

@endpoint GET /teams/ats
@desc Retrieves against-the-spread (ATS) summary by team
@required {year: int(int32) # Required year filter}
@optional {conference: str # Optional conference filter, team: str # Optional team filter}
@returns(200) Ok

@endgroup

@group roster
@endpoint GET /roster
@desc Retrieves historical roster data
@optional {team: str # Optional team filter, year: int(int32) # Optional year filter, defaults to 2025, classification: str # Optional filter to only include players from FBS or FCS teams}
@returns(200) Ok

@endgroup

@group conferences
@endpoint GET /conferences
@desc Retrieves list of conferences
@returns(200) Ok

@endgroup

@group talent
@endpoint GET /talent
@desc Retrieve 247 Team Talent Composite for a given year
@required {year: int(int32) # Year filter}
@returns(200) Ok

@endgroup

@group venues
@endpoint GET /venues
@desc Retrieve list of venues
@returns(200) Ok

@endgroup

@group stats
@endpoint GET /stats/player/season
@desc Retrieves aggregated player statistics for a given season
@required {year: int(int32) # Required year filter}
@optional {conference: str # Optional conference filter, team: str # Optional team filter, startWeek: int(int32) # Optional starting week range, endWeek: int(int32) # Optional ending week range, seasonType: str # Optional season type filter, category: str # Optional category filter}
@returns(200) Ok

@endpoint GET /stats/season
@desc Retrieves aggregated team season statistics
@optional {year: int(int32) # Year filter, required if team not specified, team: str # Team filter, required if year not specified, conference: str # Optional conference filter, startWeek: int(int32) # Optional week start range filter, endWeek: int(int32) # Optional week end range filter}
@returns(200) Ok

@endpoint GET /stats/categories
@desc Gets team statistical categories
@returns(200) Ok

@endpoint GET /stats/season/advanced
@desc Retrieves advanced season statistics for teams
@optional {year: int(int32) # Year filter, required if team not specified, team: str # Team filter, required if year not specified, excludeGarbageTime: bool # Garbage time exclusion filter, defaults to false, startWeek: int(int32) # Optional start week range filter, endWeek: int(int32) # Optional end week range filter}
@returns(200) Ok

@endpoint GET /stats/game/advanced
@desc Retrieves advanced statistics aggregated by game
@optional {year: int(int32) # Year filter, required if team not specified, team: str # Team filter, required if year not specified, week: num(double) # Optional week filter, opponent: str # Optional opponent filter, excludeGarbageTime: bool # Garbage time exclusion filter, defaults to false, seasonType: str # Optional season type filter}
@returns(200) Ok

@endpoint GET /stats/game/havoc
@desc Retrieves havoc statistics aggregated by game
@optional {year: int(int32) # Year filter, required if team not specified, team: str # Team filter, required if year not specified, week: num(double) # Optional week filter, opponent: str # Optional opponent filter, seasonType: str # Optional season type filter}
@returns(200) Ok

@endgroup

@group recruiting
@endpoint GET /recruiting/players
@desc Retrieves player recruiting rankings
@optional {year: int(int32) # Year filter, required when no team specified, team: str # Team filter, required when no team specified, position: str # Optional position categorization filter, state: str # Optional state/province filter, classification: str # Optional recruit type classification filter, defaults to HighSchool}
@returns(200) Ok

@endpoint GET /recruiting/teams
@desc Retrieves team recruiting rankings
@optional {year: int(int32) # Optional year filter, team: str # Optional team filter}
@returns(200) Ok

@endpoint GET /recruiting/groups
@desc Retrieves aggregated recruiting statistics by team and position grouping
@optional {team: str # Optional team filter, conference: str # Optional conference filter, recruitType: str # Optional recruit type filter, defaults to HighSchool, startYear: int(int32) # Optional start year range, defaults to 2000, endYear: int(int32) # Optional end year range, defaults to current year}
@returns(200) Ok

@endgroup

@group ratings
@endpoint GET /ratings/sp
@desc Retrieves SP+ ratings for a given year or school
@optional {year: int(int32) # Year filter, required if team not specified, team: str # Team filter, required if year not specified}
@returns(200) Ok

@endpoint GET /ratings/sp/conferences
@desc Retrieves aggregated historical conference SP+ data
@optional {year: int(int32) # Optional year filter, conference: str # Optional conference filter}
@returns(200) Ok

@endpoint GET /ratings/srs
@desc Retrieves historical SRS for a year or team
@optional {year: int(int32) # Year filter, required if team not specified, team: str # Team filter, required if year not specified, conference: str # Optional conference filter}
@returns(200) Ok

@endpoint GET /ratings/elo
@desc Retrieves historical Elo ratings
@optional {year: int(int32) # Optional year filter, week: int(int32) # Optional week filter, defaults to last available week in the season, seasonType: str # Optional season type filter, team: str # Optional team filter, conference: str # Optional conference filter}
@returns(200) Ok

@endpoint GET /ratings/fpi
@desc Retrieves historical Football Power Index (FPI) ratings
@optional {year: int(int32) # year filter, required if team not specified, team: str # team filter, required if year not specified, conference: str # Optional conference filter}
@returns(200) Ok

@endgroup

@group rankings
@endpoint GET /rankings
@desc Retrieves historical poll data
@required {year: int(int32) # Required year filter}
@optional {seasonType: str # Optional season type filter, week: num(double) # Optional week filter}
@returns(200) Ok

@endgroup

@group plays
@endpoint GET /plays
@desc Retrieves historical play data
@required {year: int(int32) # Required year filter, week: int(int32) # Required week filter}
@optional {team: str # Optional team filter, offense: str # Optional offensive team filter, defense: str # Optional defensive team filter, offenseConference: str # Optional offensive conference filter, defenseConference: str # Optional defensive conference filter, conference: str # Optional conference filter, playType: str # Optoinal play type abbreviation filter, seasonType: str # Optional season type filter, classification: str # Optional division classification filter}
@returns(200) Ok

@endpoint GET /plays/types
@desc Retrieves available play types
@returns(200) Ok

@endpoint GET /plays/stats
@desc Retrieve player-play associations (limit 2000)
@optional {year: int(int32) # Optional year filter, week: int(int32) # Optional week filter, team: str # Optional team filter, gameId: int(int32) # Optional gameId filter, athleteId: int(int32) # Optional athleteId filter, statTypeId: int(int32) # Optional statTypeId filter, seasonType: str # Optional season type filter, conference: str # Optional conference filter}
@returns(200) Ok

@endpoint GET /plays/stats/types
@desc Retrieves available play stat types
@returns(200) Ok

@endgroup

@group player
@endpoint GET /player/search
@desc Search for players (lists top 100 results)
@required {searchTerm: str # Search term for matching player name}
@optional {year: int(int32) # Optional year filter, team: str # Optional team filter, position: str # Optional position abbreviation filter}
@returns(200) Ok

@endpoint GET /player/usage
@desc Retrieves player usage data for a given season
@required {year: int(int32) # Required year filter}
@optional {conference: str # Optional conference abbreviation filter, position: str # Optional position abbreivation filter, team: str # Optional team filter, playerId: int(int32) # Optional player id filter, excludeGarbageTime: bool # Optional exclude garbage time flag, defaults to false}
@returns(200) Ok

@endpoint GET /player/returning
@desc Retrieves returning production data. Either a year or team filter must be specified.
@optional {year: int(int32) # Year filter, required if team not specified, team: str # Team filter, required if year not specified, conference: str # Optional conference filter}
@returns(200) Ok

@endpoint GET /player/portal
@desc Retrieves transfer portal data for a given year
@required {year: int(int32) # Required year filter}
@returns(200) Ok

@endgroup

@group ppa
@endpoint GET /ppa/predicted
@desc Query Predicted Points values by down and distance
@required {down: int(int32) # Down value, distance: int(int32) # Distance value}
@returns(200) Ok

@endpoint GET /ppa/teams
@desc Retrieves historical team PPA metrics by season
@optional {year: int(int32) # Year filter, required if team not specified, team: str # Team filter, required if year not specified, conference: str # Conference abbreviation filter, excludeGarbageTime: bool # Exclude garbage time plays}
@returns(200) Ok

@endpoint GET /ppa/games
@desc Retrieves historical team PPA metrics by game
@required {year: int(int32) # Required year filter}
@optional {week: int(int32) # Optional week filter, seasonType: str # Optional season type filter, team: str # Optional team filter, conference: str # Optional conference abbreviation filter, excludeGarbageTime: bool # Optional flag to exclude garbage time plays}
@returns(200) Ok

@endpoint GET /ppa/players/games
@desc Queries player PPA statistics by game
@required {year: int(int32) # Required year filter}
@optional {week: int(int32) # Week filter, required if team not specified, seasonType: str # Optional season type filter, team: str # Team filter, required if week not specified, position: str # Optional player position abbreviation filter, playerId: str # Optional player ID filter, threshold: num(double) # Threshold value for minimum number of plays, excludeGarbageTime: bool # Optional flag to exclude garbage time plays}
@returns(200) Ok

@endpoint GET /ppa/players/season
@desc Queries player PPA statistics by season
@optional {year: int(int32) # Year filter, required if playerId not specified, conference: str # Optional conference abbreviation filter, team: str # Optional team filter, position: str # Optional position abbreviation filter, playerId: str # Player ID filter, required if year not specified, threshold: num(double) # Threshold value for minimum number of plays, excludeGarbageTime: bool # Optional flag to exclude garbage time plays}
@returns(200) Ok

@endgroup

@group metrics
@endpoint GET /metrics/wp
@desc Query play win probabilities by game
@required {gameId: int(int32) # Required game ID filter}
@returns(200) Ok

@endpoint GET /metrics/wp/pregame
@desc Queries pregame win probabilities
@optional {year: int(int32) # Optional year filter, week: int(int32) # Optional week filter, seasonType: str # Optional season type filter, team: str # Optional team filter}
@returns(200) Ok

@endpoint GET /metrics/fg/ep
@desc Queries field goal expected points values
@returns(200) Ok

@endgroup

@group live
@endpoint GET /live/plays
@desc Queries live play-by-play data and advanced stats
@required {gameId: int(int32) # Game Id filter}
@returns(200) {id: int(int32), status: str, period: int(int32)?, clock: str, possession: str, down: int(int32)?, distance: int(int32)?, yardsToGoal: int(int32)?, teams: [map], drives: [map]} # Ok

@endgroup

@group lines
@endpoint GET /lines
@desc Retrieves historical betting data
@optional {gameId: int(int32) # Optional gameId filter, year: int(int32) # Year filter, required if game id not specified, seasonType: str # Optional season type filter, week: int(int32) # Optional week filter, team: str # Optional team filter, home: str # Optional home team filter, away: str # Optional away team filter, conference: str # Optional conference filter, provider: str # Optional provider name filter}
@returns(200) Ok

@endgroup

@group info
@endpoint GET /info
@desc Retrieves information about the user, including their Patreon level and remaining API calls.
@returns(200) UserInfo object containing patron level and remaining calls, or null if not authenticated.

@endgroup

@group games
@endpoint GET /games
@desc Retrieves historical game data
@optional {year: int(int32) # Required year filter (except when id is specified), week: int(int32) # Optional week filter, seasonType: str # Optional season type filter, classification: str # Optional division classification filter, team: str # Optional team filter, home: str # Optional home team filter, away: str # Optional away team filter, conference: str # Optional conference filter, id: int(int32) # Game id filter to retrieve a single game}
@returns(200) Ok

@endpoint GET /games/teams
@desc Retrieves team box score statistics
@optional {year: int(int32) # Required year filter (along with one of week, team, or conference), unless id is specified, week: int(int32) # Optional week filter, required if team and conference not specified, team: str # Optional team filter, required if week and conference not specified, conference: str # Optional conference filter, required if week and team not specified, classification: str # Optional division classification filter, seasonType: str # Optional season type filter, id: int(int32) # Optional id filter to retrieve a single game}
@returns(200) Ok

@endpoint GET /games/players
@desc Retrieves player box score statistics
@optional {year: int(int32) # Required year filter (along with one of week, team, or conference), unless id is specified, week: int(int32) # Optional week filter, required if team and conference not specified, team: str # Optional team filter, required if week and conference not specified, conference: str # Optional conference filter, required if week and team not specified, classification: str # Optional division classification filter, seasonType: str # Optional season type filter, category: str # Optional player statistical category filter, id: int(int32) # Optional id filter to retrieve a single game}
@returns(200) Ok

@endpoint GET /games/media
@desc Retrieves media information for games
@required {year: int(int32) # Required year filter}
@optional {seasonType: str # Optional season type filter, week: int(int32) # Optional week filter, team: str # Optional team filter, conference: str # Optional conference filter, mediaType: str # Optional media type filter, classification: str # Optional division classification filter}
@returns(200) Ok

@endpoint GET /games/weather
@desc Retrieve historical and future weather data (Patreon only)
@optional {year: int(int32) # Year filter, required if game id not specified, seasonType: str # Optional season type filter, week: int(int32) # Optional week filter, team: str # Optional team filter, conference: str # Optional conference filter, classification: str # Optional division classification filter, gameId: int(int32) # Filter for retrieving a single game}
@returns(200) Ok

@endgroup

@group records
@endpoint GET /records
@desc Retrieves historical team records
@optional {year: int(int32) # Year filter, required if team not specified, team: str # Team filter, required if year not specified, conference: str # Optional conference filter}
@returns(200) Ok

@endgroup

@group calendar
@endpoint GET /calendar
@desc Retrieves calendar information
@required {year: int(int32) # Required year filter}
@returns(200) Ok

@endgroup

@group scoreboard
@endpoint GET /scoreboard
@desc Retrieves live scoreboard data
@optional {classification: str # Optional division classification filter, defaults to fbs, conference: str # Optional conference filter}
@returns(200) Ok

@endgroup

@group drives
@endpoint GET /drives
@desc Retrieves historical drive data
@required {year: int(int32) # Required year filter}
@optional {seasonType: str # Optional season type filter, week: int(int32) # Optional week filter, team: str # Optional team filter, offense: str # Optional offensive team filter, defense: str # Optional defensive team filter, conference: str # Optional conference filter, offenseConference: str # Optional offensive team conference filter, defenseConference: str # Optional defensive team conference filter, classification: str # Optional division classification filter}
@returns(200) Ok

@endgroup

@group draft
@endpoint GET /draft/teams
@desc Retrieves list of NFL teams
@returns(200) Ok

@endpoint GET /draft/positions
@desc Retrieves list of player position categories for the NFL Draft
@returns(200) Ok

@endpoint GET /draft/picks
@desc Retrieve historical NFL draft data
@optional {year: int(int32) # Optional year filter, team: str # Optional NFL team filter, school: str # Optional college team filter, conference: str # Optional college conference filter, position: str # Optional position classification filter}
@returns(200) Ok

@endgroup

@group coaches
@endpoint GET /coaches
@desc Retrieves historical head coach information and records
@optional {firstName: str # Optional first name filter, lastName: str # Optional last name filter, team: str # Optional team filter, year: int(int32) # Optional year filter, minYear: int(int32) # Optional start year range filter, maxYear: int(int32) # Optional end year range filter}
@returns(200) Ok

@endgroup

@group game
@endpoint GET /game/box/advanced
@desc Retrieves an advanced box score for a game
@required {id: int(int32) # Required game id filter}
@returns(200) {gameInfo: map{excitement: num(double), homeWinner: bool, awayWinProb: num(double), awayPoints: int(int32), awayTeam: str, homeWinProb: num(double), homePoints: int(int32), homeTeam: str}, teams: map{fieldPosition: [map], scoringOpportunities: [map], havoc: [map], rushing: [map], explosiveness: [map], successRates: [map], cumulativePpa: [map], ppa: [map]}, players: map{ppa: [map], usage: [map]}} # Ok

@endgroup

@end