cfbd-go

module
v0.0.32 Latest Latest
Warning

This package is not in the latest version of its module.

 Go to latest Published: Jan 9, 2026 License: MIT

README

Build Status Go Reference Go Version GitHub release

CFBD Go Gopher

cfbd-go is a lightweight Go client for the collegefootballdata.com API suite

Table of Contents

Installation

go get github.com/clintrovert/cfbd-go

Quick Start

package main

import (
    "context"
    "fmt"
    "os"

    "github.com/clintrovert/cfbd-go/cfbd"
)

func main() {
    // Initialize the client with your API key
    client, err := cfbd.New(os.Getenv("CFBD_API_KEY"))
    if err != nil {
        panic(err)
    }

    ctx := context.Background()

    // Get games for a specific year
    games, err := client.GetGames(ctx, cfbd.GetGamesRequest{
        Year: 2024,
        Week: 1,
    })
    if err != nil {
        panic(err)
    }

    for _, game := range games {
        fmt.Printf("%s vs %s\n", game.AwayTeam, game.HomeTeam)
    }
}

Authentication

The CFBD API requires an API key for authentication. You can obtain an API key by:

  1. Signing up at collegefootballdata.com
  2. Getting a free API key or subscribing to Patreon for additional features

The API key is passed as a Bearer token in the Authorization header. Some endpoints require a Patreon subscription.

API Methods

Games

GetGames

GET /games

Retrieve game information with filtering options.

games, err := client.GetGames(ctx, cfbd.GetGamesRequest{
    Year: 2024,
    Week: 1,
    Team: "Texas",
    Conference: "Big 12",
    SeasonType: "regular",
})
GetGameTeams

GET /games/teams

Get team box score statistics for games.

teamStats, err := client.GetGameTeams(ctx, cfbd.GetGameTeamsRequest{
    Year: 2024,
    Week: 1,
})
GetGamePlayers

GET /games/players

Retrieve player box score statistics for games.

playerStats, err := client.GetGamePlayers(ctx, cfbd.GetGamePlayersRequest{
    Year: 2024,
    Week: 1,
    Team: "Alabama",
})
GetGameMedia

GET /games/media

Get media information for games.

media, err := client.GetGameMedia(ctx, cfbd.GetGameMediaRequest{
    Year: 2024,
    Week: 1,
})
GetGameWeather

GET /games/weather

Get weather information for games (Patreon required).

weather, err := client.GetGameWeather(ctx, cfbd.GetGameWeatherRequest{
    Year: 2024,
    Week: 1,
})
GetAdvancedBoxScore

GET /game/box/advanced

Get advanced box score statistics for a specific game.

boxScore, err := client.GetAdvancedBoxScore(ctx, cfbd.GetAdvancedBoxScoreRequest{
    GameID: 401752677,
})
GetCalendar

GET /calendar

Retrieve calendar weeks for a year.

weeks, err := client.GetCalendar(ctx, cfbd.GetCalendarRequest{
    Year: 2024,
})
GetScoreboard

GET /scoreboard

Get live scoreboard data.

scoreboard, err := client.GetScoreboard(ctx, cfbd.GetScoreboardRequest{
    Conference: "SEC",
})

Teams

GetTeams

GET /teams

Retrieve team information.

teams, err := client.GetTeams(ctx, cfbd.GetTeamsRequest{
    Conference: "SEC",
    Year: 2024,
})
GetFBSTeams

GET /teams/fbs

Get FBS (Football Bowl Subdivision) teams.

fbsTeams, err := client.GetFBSTeams(ctx, cfbd.GetFBSTeamsRequest{
    Year: 2024,
})
GetTeamRecords

GET /records

Get team records.

records, err := client.GetTeamRecords(ctx, cfbd.GetTeamRecordsRequest{
    Team: "Texas",
    Year: 2024,
})
GetTeamMatchup

GET /teams/matchup

Get historical matchup data between two teams.

matchup, err := client.GetTeamMatchup(ctx, cfbd.GetTeamMatchupRequest{
    Team1: "Texas",
    Team2: "Oklahoma",
    MinYear: 2020,
    MaxYear: 2024,
})
GetTeamATS

GET /teams/ats

Get team against-the-spread records.

ats, err := client.GetTeamATS(ctx, cfbd.GetTeamATSRequest{
    Year: 2024,
    Conference: "SEC",
})
GetRoster

GET /roster

Get team roster information.

roster, err := client.GetRoster(ctx, cfbd.GetRosterRequest{
    Team: "Alabama",
    Year: 2024,
})
GetTeamTalentComposite

GET /talent

Get 247 team talent composite ratings.

talent, err := client.GetTeamTalentComposite(ctx, cfbd.GetTalentCompositeRequest{
    Year: 2024,
})

Players

SearchPlayers

GET /player/search

Search for players by name or other criteria.

players, err := client.SearchPlayers(ctx, cfbd.SearchPlayersRequest{
    SearchTerm: "Smith",
    Year: 2024,
    Team: "Alabama",
})
GetPlayerUsage

GET /player/usage

Get player usage statistics.

usage, err := client.GetPlayerUsage(ctx, cfbd.GetPlayerUsageRequest{
    Year: 2024,
    Team: "Texas",
    Position: "QB",
})
GetReturningProduction

GET /player/returning

Get returning production statistics for players.

production, err := client.GetReturningProduction(ctx, cfbd.GetReturningProductionRequest{
    Year: 2024,
    Team: "Alabama",
})
GetTransferPortalPlayers

GET /player/portal

Get transfer portal player information.

transfers, err := client.GetTransferPortalPlayers(ctx, cfbd.GetTransferPortalPlayersRequest{
    Year: 2024,
})

Plays and Drives

GetPlays

GET /plays

Get play-by-play data for games.

plays, err := client.GetPlays(ctx, cfbd.GetPlaysRequest{
    Year: 2024,
    Week: 1,
    Team: "Texas",
})
GetPlayTypes

GET /plays/types

Get all available play types.

playTypes, err := client.GetPlayTypes(ctx)
GetPlayStats

GET /plays/stats

Get play statistics.

stats, err := client.GetPlayStats(ctx, cfbd.GetPlayStatsRequest{
    Year: 2024,
    Week: 1,
    GameID: 401767768,
})
GetPlayStatTypes

GET /plays/stats/types

Get all available play statistic types.

statTypes, err := client.GetPlayStatTypes(ctx)
GetLivePlays

GET /live/plays

Get live play-by-play data for a game (requires live game ID).

liveGame, err := client.GetLivePlays(ctx, cfbd.GetLivePlaysRequest{
    GameID: 401778330,
})
GetDrives

GET /drives

Get drive information for games.

drives, err := client.GetDrives(ctx, cfbd.GetDrivesRequest{
    Year: 2024,
    Week: 1,
    Team: "Alabama",
})

Statistics

GetPlayerSeasonStats

GET /stats/player/season

Get player season statistics.

stats, err := client.GetPlayerSeasonStats(ctx, cfbd.GetPlayerSeasonStatsRequest{
    Year: 2024,
    Team: "Texas",
    Category: "passing",
})
GetTeamSeasonStats

GET /stats/season

Get team season statistics.

stats, err := client.GetTeamSeasonStats(ctx, cfbd.GetTeamSeasonStatsRequest{
    Year: 2024,
    Team: "Alabama",
})
GetAdvancedSeasonStats

GET /stats/season/advanced

Get advanced season statistics.

stats, err := client.GetAdvancedSeasonStats(ctx, cfbd.GetAdvancedSeasonStatsRequest{
    Year: 2024,
    Team: "Texas",
    ExcludeGarbageTime: &excludeGarbage,
})
GetAdvancedGameStats

GET /stats/game/advanced

Get advanced game statistics.

stats, err := client.GetAdvancedGameStats(ctx, cfbd.GetAdvancedGameStatsRequest{
    Year: 2024,
    Week: 1,
    Team: "Alabama",
})
GetHavocGameStats

GET /stats/game/havoc

Get havoc game statistics.

stats, err := client.GetHavocGameStats(ctx, cfbd.GetHavocGameStatsRequest{
    Year: 2024,
    Week: 1,
    Team: "Texas",
})
GetStatCategories

GET /stats/categories

Get all available statistics categories.

categories, err := client.GetStatCategories(ctx)

Ratings

GetTeamSPPlusRatings

GET /ratings/sp

Get SP+ (S&P+) ratings for teams.

ratings, err := client.GetTeamSPPlusRatings(ctx, cfbd.GetSPPlusRatingsRequest{
    Year: 2024,
    Team: "Alabama",
})
GetConferenceSPPlusRatings

GET /ratings/sp/conferences

Get SP+ ratings for conferences.

ratings, err := client.GetConferenceSPPlusRatings(ctx, cfbd.GetConferenceSPPlusRatingsRequest{
    Year: 2024,
    Conference: "SEC",
})
GetSRSRatings

GET /ratings/srs

Get SRS (Simple Rating System) ratings.

ratings, err := client.GetSRSRatings(ctx, cfbd.GetSRSRatingsRequest{
    Year: 2024,
    Team: "Texas",
})
GetEloRatings

GET /ratings/elo

Get Elo ratings for teams.

ratings, err := client.GetEloRatings(ctx, cfbd.GetEloRatingsRequest{
    Year: 2024,
    Week: 1,
    Team: "Alabama",
})
GetFPIRatings

GET /ratings/fpi

Get FPI (Football Power Index) ratings.

ratings, err := client.GetFPIRatings(ctx, cfbd.GetFPIRatingsRequest{
    Year: 2024,
    Team: "Texas",
})

Rankings

GetRankings

GET /rankings

Get college football rankings (polls).

rankings, err := client.GetRankings(ctx, cfbd.GetRankingsRequest{
    Year: 2024,
    Week: 1,
    SeasonType: "regular",
})

Betting

GetBettingLines

GET /lines

Get betting lines for games.

lines, err := client.GetBettingLines(ctx, cfbd.GetBettingLinesRequest{
    Year: 2024,
    Week: 1,
    Provider: "fanduel",
})

Recruiting

GetPlayerRecruitingRankings

GET /recruiting/players

Get player recruiting rankings.

recruits, err := client.GetPlayerRecruitingRankings(ctx, cfbd.GetPlayersRecruitingRankingsRequest{
    Year: 2024,
    Team: "Alabama",
    Position: "QB",
})
GetTeamRecruitingRankings

GET /recruiting/teams

Get team recruiting rankings.

rankings, err := client.GetTeamRecruitingRankings(ctx, cfbd.GetTeamRecruitingRankingsRequest{
    Year: 2024,
    Team: "Texas",
})
GetTeamPositionGroupRecruitingRankings

GET /recruiting/groups

Get aggregated team recruiting information by position group.

groups, err := client.GetTeamPositionGroupRecruitingRankings(ctx, cfbd.GetTeamPositionGroupRecruitingRankingsRequest{
    Team: "Alabama",
    StartYear: 2020,
    EndYear: 2024,
})

Metrics

GetPredictedPoints

GET /ppa/predicted

Get predicted points values by down and distance.

points, err := client.GetPredictedPoints(ctx, cfbd.GetPredictedPointsRequest{
    Down: 2,
    Distance: 10,
})
GetTeamsPPA

GET /ppa/teams

Get team season PPA (Predicted Points Added) statistics.

ppa, err := client.GetTeamsPPA(ctx, cfbd.GetTeamsPPARequest{
    Year: 2024,
    Team: "Texas",
})
GetGamesPPA

GET /ppa/games

Get team game PPA statistics.

ppa, err := client.GetGamesPPA(ctx, cfbd.GetPpaGamesRequest{
    Year: 2024,
    Week: 1,
    Team: "Alabama",
})
GetPlayersPPA

GET /ppa/players/games

Get player game PPA statistics.

ppa, err := client.GetPlayersPPA(ctx, cfbd.GetPlayerPpaGamesRequest{
    Year: 2024,
    Week: 1,
    Team: "Texas",
    Position: "QB",
})
GetPlayerSeasonPPA

GET /ppa/players/season

Get player season PPA statistics.

ppa, err := client.GetPlayerSeasonPPA(ctx, cfbd.GetPlayerSeasonPPARequest{
    Year: 2024,
    Team: "Alabama",
    Position: "RB",
})
GetWinProbability

GET /metrics/wp

Get win probability data for each play in a game.

probabilities, err := client.GetWinProbability(ctx, cfbd.GetWinProbabilityRequest{
    GameID: 401778330,
})
GetPregameWinProbability

GET /metrics/wp/pregame

Get pregame win probability data.

probabilities, err := client.GetPregameWinProbability(ctx, cfbd.GetPregameWpRequest{
    Year: 2024,
    Week: 1,
    Team: "Texas",
})
GetFieldGoalExpectedPoints

GET /metrics/fg/ep

Get field goal expected points values.

ep, err := client.GetFieldGoalExpectedPoints(ctx)

Adjusted Metrics (Patreon Required)

GetTeamSeasonWEPA

GET /wepa/team/season

Get team season WEPA (Weighted Expected Points Added) metrics.

wepa, err := client.GetTeamSeasonWEPA(ctx, cfbd.GetTeamSeasonWEPARequest{
    Year: 2024,
    Team: "Alabama",
})
GetPlayerPassingWEPA

GET /wepa/players/passing

Get player passing WEPA metrics.

wepa, err := client.GetPlayerPassingWEPA(ctx, cfbd.GetPlayerWEPARequest{
    Year: 2024,
    Team: "Texas",
    Position: "QB",
})
GetPlayerRushingWEPA

GET /wepa/players/rushing

Get player rushing WEPA metrics.

wepa, err := client.GetPlayerRushingWEPA(ctx, cfbd.GetPlayerWEPARequest{
    Year: 2024,
    Team: "Alabama",
    Position: "RB",
})
GetPlayerKickingWEPA

GET /wepa/players/kicking

Get kicker PAAR (Points Above Average Replacement) metrics.

paar, err := client.GetPlayerKickingWEPA(ctx, cfbd.GetWepaPlayersKickingRequest{
    Year: 2024,
    Team: "Texas",
})

Draft

GetDraftTeams

GET /draft/teams

Get all NFL draft teams.

teams, err := client.GetDraftTeams(ctx)
GetDraftPositions

GET /draft/positions

Get all NFL draft positions.

positions, err := client.GetDraftPositions(ctx)
GetDraftPicks

GET /draft/picks

Get NFL draft picks.

picks, err := client.GetDraftPicks(ctx, cfbd.GetDraftPicksRequest{
    Year: 2024,
    Team: "Dallas Cowboys",
    School: "Alabama",
})

Reference Data

GetConferences

GET /conferences

Get all available conferences.

conferences, err := client.GetConferences(ctx)
GetVenues

GET /venues

Get all available venues.

venues, err := client.GetVenues(ctx)
GetCoaches

GET /coaches

Get coach information.

coaches, err := client.GetCoaches(ctx, cfbd.GetCoachesRequest{
    Team: "Alabama",
    Year: 2024,
})

User Information

GetInfo

GET /info

Get information about the authenticated user's API key.

info, err := client.GetInfo(ctx)
if info != nil {
    fmt.Printf("User: %s\n", info.Email)
}

Error Handling

The client returns errors for various conditions:

  • ErrMissingAPIKey: Returned when the API key is empty
  • ErrMissingRequiredParams: Returned when required parameters are missing
  • Network and API errors are wrapped with context
client, err := cfbd.New("")
if err == cfbd.ErrMissingAPIKey {
    // Handle missing API key
}

games, err := client.GetGames(ctx, cfbd.GetGamesRequest{})
if err != nil {
    // Handle API error
}

Context Support

All methods accept a context.Context for cancellation and timeouts:

ctx, cancel := context.WithTimeout(context.Background(), 5*time.Second)
defer cancel()

games, err := client.GetGames(ctx, cfbd.GetGamesRequest{Year: 2024})

Patreon Subscriptions

Some endpoints require a Patreon subscription:

  • Weather data (GetGameWeather)
  • Adjusted metrics (WEPA endpoints)
  • Some advanced statistics

Check the CFBD API documentation for the latest list of Patreon-only features.

Examples

See the examples directory for comprehensive usage examples covering all API endpoints.

License

See LICENSE file for details.

Contributing

Contributions are welcome! Please open an issue or submit a pull request.

Branch Naming and Versioning

This project uses semantic versioning (semver) with automated version calculation based on branch names. When creating a pull request, prefix your branch name with one of the following to indicate the type of change:

  • major/ - For breaking changes that require a major version bump

    • Example: major/breaking-api-changes
    • Result: v2.0.0 (if previous was v1.x.x)

  • minor/ - For new features that are backward compatible

    • Example: minor/add-new-endpoint
    • Result: v1.2.0 (if previous was v1.1.x)

  • patch/ - For bug fixes and other backward-compatible changes

    • Example: patch/fix-bug
    • Result: v1.1.1 (if previous was v1.1.0)

Note: If no prefix is provided, the default is a patch version bump.

Workflow

  1. Create a branch with the appropriate prefix (major/, minor/, or patch/)
  2. Make your changes
  3. Ensure tests pass (go test ./...)
  4. Submit a pull request
  5. The CI workflow will:
    • Run all tests
    • Calculate and comment the suggested next release version on your PR
  6. When your PR is merged, a new release will be automatically created with the calculated version

For more details, see the GitHub workflows for test and release automation.

Directories

Path Synopsis
Package cfbd provides a minimal, type-safe Golang client for the College Football Data API.
 Package cfbd provides a minimal, type-safe Golang client for the College Football Data API.
internal/httpget
Package httpget provides an HTTP client wrapper for dependency injection and testing.
 Package httpget provides an HTTP client wrapper for dependency injection and testing.

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL
go.dev uses cookies from Google to deliver and enhance the quality of its services and to analyze traffic. Learn more.