{"note":"OpenAPI conversion -- returning structured metadata","name":"collegefootballdata-com","description":"College Football Data API","version":"5.13.2","base_url":"https://api.collegefootballdata.com/","endpoints":60,"raw":"@lap v0.3\n# Machine-readable API spec. Each @endpoint block is one API call.\n@api College Football Data API\n@base https://api.collegefootballdata.com/\n@version 5.13.2\n@auth Bearer bearer\n@endpoints 60\n@hint download_for_search\n@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)\n\n@group wepa\n@endpoint GET /wepa/team/season\n@desc Retrieve opponent-adjusted team season statistics\n@optional {year: int(int32) # Optional year filter, team: str # Optional team filter, conference: str # Optional conference filter}\n@returns(200) Ok\n\n@endpoint GET /wepa/players/passing\n@desc Retrieve opponent-adjusted player passing statistics\n@optional {year: int(int32) # Optional year filter, team: str # Optional team filter, conference: str # Optional conference abbreviation filter, position: str # Optional position abbreviation filter}\n@returns(200) Ok\n\n@endpoint GET /wepa/players/rushing\n@desc Retrieve opponent-adjusted player rushing statistics\n@optional {year: int(int32) # Optional year filter, team: str # Optional team filter, conference: str # Optional conference abbreviation filter, position: str # Optional position abbreviation filter}\n@returns(200) Ok\n\n@endpoint GET /wepa/players/kicking\n@desc Retrieve Points Added Above Replacement (PAAR) ratings for kickers\n@optional {year: int(int32) # Optional year filter, team: str # Optional team filter, conference: str # Optional conference abbreviation filter}\n@returns(200) Ok\n\n@endgroup\n\n@group teams\n@endpoint GET /teams\n@desc Retrieves team information\n@optional {conference: str # Optional conference abbreviation filter, year: int(int32) # Optional year filter to get historical conference affiliations}\n@returns(200) Ok\n\n@endpoint GET /teams/fbs\n@desc Retrieves information on teams playing in the highest division of CFB\n@optional {year: int(int32) # Year or season}\n@returns(200) Ok\n\n@endpoint GET /teams/matchup\n@desc Retrieves historical matchup details for two given teams\n@required {team1: str # First team to compare, team2: str # Second team to compare}\n@optional {minYear: int(int32) # Optional starting year, maxYear: int(int32) # Optional ending year}\n@returns(200) {team1: str, team2: str, startYear: int(int32), endYear: int(int32), team1Wins: int(int32), team2Wins: int(int32), ties: int(int32), games: [map]} # Ok\n\n@endpoint GET /teams/ats\n@desc Retrieves against-the-spread (ATS) summary by team\n@required {year: int(int32) # Required year filter}\n@optional {conference: str # Optional conference filter, team: str # Optional team filter}\n@returns(200) Ok\n\n@endgroup\n\n@group roster\n@endpoint GET /roster\n@desc Retrieves historical roster data\n@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}\n@returns(200) Ok\n\n@endgroup\n\n@group conferences\n@endpoint GET /conferences\n@desc Retrieves list of conferences\n@returns(200) Ok\n\n@endgroup\n\n@group talent\n@endpoint GET /talent\n@desc Retrieve 247 Team Talent Composite for a given year\n@required {year: int(int32) # Year filter}\n@returns(200) Ok\n\n@endgroup\n\n@group venues\n@endpoint GET /venues\n@desc Retrieve list of venues\n@returns(200) Ok\n\n@endgroup\n\n@group stats\n@endpoint GET /stats/player/season\n@desc Retrieves aggregated player statistics for a given season\n@required {year: int(int32) # Required year filter}\n@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}\n@returns(200) Ok\n\n@endpoint GET /stats/season\n@desc Retrieves aggregated team season statistics\n@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}\n@returns(200) Ok\n\n@endpoint GET /stats/categories\n@desc Gets team statistical categories\n@returns(200) Ok\n\n@endpoint GET /stats/season/advanced\n@desc Retrieves advanced season statistics for teams\n@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}\n@returns(200) Ok\n\n@endpoint GET /stats/game/advanced\n@desc Retrieves advanced statistics aggregated by game\n@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}\n@returns(200) Ok\n\n@endpoint GET /stats/game/havoc\n@desc Retrieves havoc statistics aggregated by game\n@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}\n@returns(200) Ok\n\n@endgroup\n\n@group recruiting\n@endpoint GET /recruiting/players\n@desc Retrieves player recruiting rankings\n@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}\n@returns(200) Ok\n\n@endpoint GET /recruiting/teams\n@desc Retrieves team recruiting rankings\n@optional {year: int(int32) # Optional year filter, team: str # Optional team filter}\n@returns(200) Ok\n\n@endpoint GET /recruiting/groups\n@desc Retrieves aggregated recruiting statistics by team and position grouping\n@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}\n@returns(200) Ok\n\n@endgroup\n\n@group ratings\n@endpoint GET /ratings/sp\n@desc Retrieves SP+ ratings for a given year or school\n@optional {year: int(int32) # Year filter, required if team not specified, team: str # Team filter, required if year not specified}\n@returns(200) Ok\n\n@endpoint GET /ratings/sp/conferences\n@desc Retrieves aggregated historical conference SP+ data\n@optional {year: int(int32) # Optional year filter, conference: str # Optional conference filter}\n@returns(200) Ok\n\n@endpoint GET /ratings/srs\n@desc Retrieves historical SRS for a year or team\n@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}\n@returns(200) Ok\n\n@endpoint GET /ratings/elo\n@desc Retrieves historical Elo ratings\n@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}\n@returns(200) Ok\n\n@endpoint GET /ratings/fpi\n@desc Retrieves historical Football Power Index (FPI) ratings\n@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}\n@returns(200) Ok\n\n@endgroup\n\n@group rankings\n@endpoint GET /rankings\n@desc Retrieves historical poll data\n@required {year: int(int32) # Required year filter}\n@optional {seasonType: str # Optional season type filter, week: num(double) # Optional week filter}\n@returns(200) Ok\n\n@endgroup\n\n@group plays\n@endpoint GET /plays\n@desc Retrieves historical play data\n@required {year: int(int32) # Required year filter, week: int(int32) # Required week filter}\n@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}\n@returns(200) Ok\n\n@endpoint GET /plays/types\n@desc Retrieves available play types\n@returns(200) Ok\n\n@endpoint GET /plays/stats\n@desc Retrieve player-play associations (limit 2000)\n@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}\n@returns(200) Ok\n\n@endpoint GET /plays/stats/types\n@desc Retrieves available play stat types\n@returns(200) Ok\n\n@endgroup\n\n@group player\n@endpoint GET /player/search\n@desc Search for players (lists top 100 results)\n@required {searchTerm: str # Search term for matching player name}\n@optional {year: int(int32) # Optional year filter, team: str # Optional team filter, position: str # Optional position abbreviation filter}\n@returns(200) Ok\n\n@endpoint GET /player/usage\n@desc Retrieves player usage data for a given season\n@required {year: int(int32) # Required year filter}\n@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}\n@returns(200) Ok\n\n@endpoint GET /player/returning\n@desc Retrieves returning production data. Either a year or team filter must be specified.\n@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}\n@returns(200) Ok\n\n@endpoint GET /player/portal\n@desc Retrieves transfer portal data for a given year\n@required {year: int(int32) # Required year filter}\n@returns(200) Ok\n\n@endgroup\n\n@group ppa\n@endpoint GET /ppa/predicted\n@desc Query Predicted Points values by down and distance\n@required {down: int(int32) # Down value, distance: int(int32) # Distance value}\n@returns(200) Ok\n\n@endpoint GET /ppa/teams\n@desc Retrieves historical team PPA metrics by season\n@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}\n@returns(200) Ok\n\n@endpoint GET /ppa/games\n@desc Retrieves historical team PPA metrics by game\n@required {year: int(int32) # Required year filter}\n@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}\n@returns(200) Ok\n\n@endpoint GET /ppa/players/games\n@desc Queries player PPA statistics by game\n@required {year: int(int32) # Required year filter}\n@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}\n@returns(200) Ok\n\n@endpoint GET /ppa/players/season\n@desc Queries player PPA statistics by season\n@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}\n@returns(200) Ok\n\n@endgroup\n\n@group metrics\n@endpoint GET /metrics/wp\n@desc Query play win probabilities by game\n@required {gameId: int(int32) # Required game ID filter}\n@returns(200) Ok\n\n@endpoint GET /metrics/wp/pregame\n@desc Queries pregame win probabilities\n@optional {year: int(int32) # Optional year filter, week: int(int32) # Optional week filter, seasonType: str # Optional season type filter, team: str # Optional team filter}\n@returns(200) Ok\n\n@endpoint GET /metrics/fg/ep\n@desc Queries field goal expected points values\n@returns(200) Ok\n\n@endgroup\n\n@group live\n@endpoint GET /live/plays\n@desc Queries live play-by-play data and advanced stats\n@required {gameId: int(int32) # Game Id filter}\n@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\n\n@endgroup\n\n@group lines\n@endpoint GET /lines\n@desc Retrieves historical betting data\n@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}\n@returns(200) Ok\n\n@endgroup\n\n@group info\n@endpoint GET /info\n@desc Retrieves information about the user, including their Patreon level and remaining API calls.\n@returns(200) UserInfo object containing patron level and remaining calls, or null if not authenticated.\n\n@endgroup\n\n@group games\n@endpoint GET /games\n@desc Retrieves historical game data\n@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}\n@returns(200) Ok\n\n@endpoint GET /games/teams\n@desc Retrieves team box score statistics\n@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}\n@returns(200) Ok\n\n@endpoint GET /games/players\n@desc Retrieves player box score statistics\n@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}\n@returns(200) Ok\n\n@endpoint GET /games/media\n@desc Retrieves media information for games\n@required {year: int(int32) # Required year filter}\n@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}\n@returns(200) Ok\n\n@endpoint GET /games/weather\n@desc Retrieve historical and future weather data (Patreon only)\n@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}\n@returns(200) Ok\n\n@endgroup\n\n@group records\n@endpoint GET /records\n@desc Retrieves historical team records\n@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}\n@returns(200) Ok\n\n@endgroup\n\n@group calendar\n@endpoint GET /calendar\n@desc Retrieves calendar information\n@required {year: int(int32) # Required year filter}\n@returns(200) Ok\n\n@endgroup\n\n@group scoreboard\n@endpoint GET /scoreboard\n@desc Retrieves live scoreboard data\n@optional {classification: str # Optional division classification filter, defaults to fbs, conference: str # Optional conference filter}\n@returns(200) Ok\n\n@endgroup\n\n@group drives\n@endpoint GET /drives\n@desc Retrieves historical drive data\n@required {year: int(int32) # Required year filter}\n@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}\n@returns(200) Ok\n\n@endgroup\n\n@group draft\n@endpoint GET /draft/teams\n@desc Retrieves list of NFL teams\n@returns(200) Ok\n\n@endpoint GET /draft/positions\n@desc Retrieves list of player position categories for the NFL Draft\n@returns(200) Ok\n\n@endpoint GET /draft/picks\n@desc Retrieve historical NFL draft data\n@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}\n@returns(200) Ok\n\n@endgroup\n\n@group coaches\n@endpoint GET /coaches\n@desc Retrieves historical head coach information and records\n@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}\n@returns(200) Ok\n\n@endgroup\n\n@group game\n@endpoint GET /game/box/advanced\n@desc Retrieves an advanced box score for a game\n@required {id: int(int32) # Required game id filter}\n@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\n\n@endgroup\n\n@end\n"}