College Football Data

/**
 * CollegeFootballData - generated by OmniStream from College Football Data's OpenAPI spec.
 * One typed method per endpoint. A single Omni key reaches the API.
 */
const DEFAULT_BASE = "https://grid.skinvaults.online/v1/proxy/cfbdata";

export class CollegeFootballDataError extends Error {
  status: number;
  code?: string;
  constructor(status: number, code: string | undefined, message?: string) {
    super(message || `CollegeFootballData error ${status}`);
    this.name = "CollegeFootballDataError";
    this.status = status;
    this.code = code;
  }
}

export interface CollegeFootballDataOptions {
  baseUrl?: string;
  fetch?: typeof fetch;
  timeoutMs?: number;
}

export class CollegeFootballData {
  /** @param token Your OmniStream key (one key for every API). */
  constructor(private token: string, private opts: CollegeFootballDataOptions = {}) {
    if (!token) throw new Error("CollegeFootballData: token is required");
  }
  rateLimit: { remainingMinute?: number; remainingDay?: number } | null = null;

  private async _request(method: string, path: string, { params, body }: { params?: Record<string, unknown>; body?: unknown } = {}): Promise<any> {
    const f = this.opts.fetch ?? globalThis.fetch;
    const url = new URL((this.opts.baseUrl ?? DEFAULT_BASE).replace(/\/+$/, "") + path);
    if (params) for (const [k, v] of Object.entries(params)) if (v != null) url.searchParams.set(k, String(v));
    const headers: Record<string, string> = { "x-omni-key": this.token };
    if (body !== undefined) headers["content-type"] = "application/json";
    const res = await f(url, { method, headers, body: body !== undefined ? JSON.stringify(body) : undefined });
    this.rateLimit = {
      remainingMinute: Number(res.headers.get("x-ratelimit-remaining-minute")) || undefined,
      remainingDay: Number(res.headers.get("x-ratelimit-remaining-day")) || undefined,
    };
    const data = await res.json().catch(() => ({}));
    if (!res.ok) throw new CollegeFootballDataError(res.status, data?.error?.code, data?.error?.message);
    return data.data ?? data;
  }

  /** Season calendar */
  getCalendar(params: { "year": number }): Promise<any> {
    return this._request("GET", "/calendar", { params });
  }

  /** Coaching records and history */
  getCoaches(params: { "firstName"?: string; "lastName"?: string; "team"?: string; "year"?: number; "minYear"?: number; "maxYear"?: number }): Promise<any> {
    return this._request("GET", "/coaches", { params });
  }

  /** Conferences */
  getConferences(): Promise<any> {
    return this._request("GET", "/conferences", {});
  }

  /** List of NFL Draft picks */
  getDraftPicks(params: { "year"?: number; "nflTeam"?: string; "college"?: string; "conference"?: string; "position"?: string }): Promise<any> {
    return this._request("GET", "/draft/picks", { params });
  }

  /** List of NFL positions */
  getNFLPositions(): Promise<any> {
    return this._request("GET", "/draft/positions", {});
  }

  /** List of NFL teams */
  getNFLTeams(): Promise<any> {
    return this._request("GET", "/draft/teams", {});
  }

  /** Drive data and results */
  getDrives(params: { "year": number; "seasonType"?: string; "week"?: number; "team"?: string; "offense"?: string; "defense"?: string; "conference"?: string; "offenseConference"?: string; "defenseConference"?: string; "classification"?: string }): Promise<any> {
    return this._request("GET", "/drives", { params });
  }

  /** Advanced box scores */
  getAdvancedBoxScore(params: { "gameId": number }): Promise<any> {
    return this._request("GET", "/game/box/advanced", { params });
  }

  /** Games and results */
  getGames(params: { "year": number; "week"?: number; "seasonType"?: string; "team"?: string; "home"?: string; "away"?: string; "conference"?: string; "division"?: string; "id"?: number }): Promise<any> {
    return this._request("GET", "/games", { params });
  }

  /** Game media information and schedules */
  getGameMedia(params: { "year": number; "week"?: number; "seasonType"?: string; "team"?: string; "conference"?: string; "mediaType"?: string; "classification"?: string }): Promise<any> {
    return this._request("GET", "/games/media", { params });
  }

  /** Player game stats */
  getPlayerGameStats(params: { "year": number; "week"?: number; "seasonType"?: string; "team"?: string; "conference"?: string; "category"?: string; "gameId"?: number }): Promise<any> {
    return this._request("GET", "/games/players", { params });
  }

  /** Team game stats */
  getTeamGameStats(params: { "year": number; "week"?: number; "seasonType"?: string; "team"?: string; "conference"?: string; "gameId"?: number; "classification"?: string }): Promise<any> {
    return this._request("GET", "/games/teams", { params });
  }

  /** Game weather information (Patreon only) */
  getGameWeather(params: { "gameId"?: number; "year"?: number; "week"?: number; "seasonType"?: string; "team"?: string; "conference"?: string; "classification"?: string }): Promise<any> {
    return this._request("GET", "/games/weather", { params });
  }

  /** Betting lines */
  getLines(params: { "gameId"?: number; "year"?: number; "week"?: number; "seasonType"?: string; "team"?: string; "home"?: string; "away"?: string; "conference"?: string }): Promise<any> {
    return this._request("GET", "/lines", { params });
  }

  /** Live metrics and PBP (Patreon only) */
  getLivePlays(params: { "id": number }): Promise<any> {
    return this._request("GET", "/live/plays", { params });
  }

  /** Win probability chart data */
  getWinProbabilityData(params: { "gameId": number }): Promise<any> {
    return this._request("GET", "/metrics/wp", { params });
  }

  /** Pregame win probability data */
  getPregameWinProbabilities(params: { "year"?: number; "week"?: number; "team"?: string; "seasonType"?: string }): Promise<any> {
    return this._request("GET", "/metrics/wp/pregame", { params });
  }

  /** Types of player play stats */
  getPlayStatTypes(): Promise<any> {
    return this._request("GET", "/play/stat/types", {});
  }

  /** Play stats by play */
  getPlayStats(params: { "year"?: number; "week"?: number; "team"?: string; "gameId"?: number; "athleteId"?: number; "statTypeId"?: number; "seasonType"?: string; "conference"?: string }): Promise<any> {
    return this._request("GET", "/play/stats", { params });
  }

  /** Play types */
  getPlayTypes(): Promise<any> {
    return this._request("GET", "/play/types", {});
  }

  /** Transfer portal by season */
  getTransferPortal(params: { "year": number }): Promise<any> {
    return this._request("GET", "/player/portal", { params });
  }

  /** Team returning production metrics */
  getReturningProduction(params: { "year"?: number; "team"?: string; "conference"?: string }): Promise<any> {
    return this._request("GET", "/player/returning", { params });
  }

  /** Search for player information */
  playerSearch(params: { "searchTerm": string; "position"?: string; "team"?: string; "year"?: number }): Promise<any> {
    return this._request("GET", "/player/search", { params });
  }

  /** Player usage metrics broken down by season */
  getPlayerUsage(params: { "year": number; "team"?: string; "conference"?: string; "position"?: string; "playerId"?: number; "excludeGarbageTime"?: boolean }): Promise<any> {
    return this._request("GET", "/player/usage", { params });
  }

  /** Play by play data */
  getPlays(params: { "year": number; "week": number; "seasonType"?: string; "team"?: string; "offense"?: string; "defense"?: string; "conference"?: string; "offenseConference"?: string; "defenseConference"?: string; "playType"?: number; "classification"?: string }): Promise<any> {
    return this._request("GET", "/plays", { params });
  }

  /** Team Predicated Points Added (PPA/EPA) by game */
  getGamePPA(params: { "year": number; "week"?: number; "team"?: string; "conference"?: string; "excludeGarbageTime"?: boolean; "seasonType"?: string }): Promise<any> {
    return this._request("GET", "/ppa/games", { params });
  }

  /** Player Predicated Points Added (PPA/EPA) broken down by game */
  getPlayerGamePPA(params: { "year"?: number; "week"?: number; "team"?: string; "position"?: string; "playerId"?: number; "threshold"?: string; "excludeGarbageTime"?: boolean; "seasonType"?: string }): Promise<any> {
    return this._request("GET", "/ppa/players/games", { params });
  }

  /** Player Predicated Points Added (PPA/EPA) broken down by season */
  getPlayerSeasonPPA(params: { "year"?: number; "team"?: string; "conference"?: string; "position"?: string; "playerId"?: number; "threshold"?: string; "excludeGarbageTime"?: boolean }): Promise<any> {
    return this._request("GET", "/ppa/players/season", { params });
  }

  /** Predicted Points (i.e. Expected Points or EP) */
  getPredictedPoints(params: { "down": number; "distance": number }): Promise<any> {
    return this._request("GET", "/ppa/predicted", { params });
  }

  /** Predicted Points Added (PPA/EPA) data by team */
  getTeamPPA(params: { "year"?: number; "team"?: string; "conference"?: string; "excludeGarbageTime"?: boolean }): Promise<any> {
    return this._request("GET", "/ppa/teams", { params });
  }

  /** Historical polls and rankings */
  getRankings(params: { "year": number; "week"?: number; "seasonType"?: string }): Promise<any> {
    return this._request("GET", "/rankings", { params });
  }

  /** Historical Elo ratings */
  getEloRatings(params: { "year"?: number; "week"?: number; "team"?: string; "conference"?: string }): Promise<any> {
    return this._request("GET", "/ratings/elo", { params });
  }

  /** Historical SP+ ratings */
  getSPRatings(params: { "year"?: number; "team"?: string }): Promise<any> {
    return this._request("GET", "/ratings/sp", { params });
  }

  /** Historical SP+ ratings by conference */
  getConferenceSPRatings(params: { "year"?: number; "conference"?: string }): Promise<any> {
    return this._request("GET", "/ratings/sp/conferences", { params });
  }

  /** Historical SRS ratings */
  getSRSRatings(params: { "year"?: number; "team"?: string; "conference"?: string }): Promise<any> {
    return this._request("GET", "/ratings/srs", { params });
  }

  /** Team records */
  getTeamRecords(params: { "year"?: number; "team"?: string; "conference"?: string }): Promise<any> {
    return this._request("GET", "/records", { params });
  }

  /** Recruit position group ratings */
  getRecruitingGroups(params: { "startYear"?: number; "endYear"?: number; "team"?: string; "conference"?: string }): Promise<any> {
    return this._request("GET", "/recruiting/groups", { params });
  }

  /** Player recruiting ratings and rankings */
  getRecruitingPlayers(params: { "year"?: number; "classification"?: string; "position"?: string; "state"?: string; "team"?: string }): Promise<any> {
    return this._request("GET", "/recruiting/players", { params });
  }

  /** Team recruiting rankings and ratings */
  getRecruitingTeams(params: { "year"?: number; "team"?: string }): Promise<any> {
    return this._request("GET", "/recruiting/teams", { params });
  }

  /** Team rosters */
  getRoster(params: { "team"?: string; "year"?: number }): Promise<any> {
    return this._request("GET", "/roster", { params });
  }

  /** Live game results (Patreon only) */
  getScoreboard(params: { "classification"?: string; "conference"?: string }): Promise<any> {
    return this._request("GET", "/scoreboard", { params });
  }

  /** Team stat categories */
  getStatCategories(): Promise<any> {
    return this._request("GET", "/stats/categories", {});
  }

  /** Advanced team metrics by game */
  getAdvancedTeamGameStats(params: { "year"?: number; "week"?: number; "team"?: string; "opponent"?: string; "excludeGarbageTime"?: boolean; "seasonType"?: string }): Promise<any> {
    return this._request("GET", "/stats/game/advanced", { params });
  }

  /** Player stats by season */
  getPlayerSeasonStats(params: { "year": number; "team"?: string; "conference"?: string; "startWeek"?: number; "endWeek"?: number; "seasonType"?: string; "category"?: string }): Promise<any> {
    return this._request("GET", "/stats/player/season", { params });
  }

  /** Team statistics by season */
  getTeamSeasonStats(params: { "year"?: number; "team"?: string; "conference"?: string; "startWeek"?: number; "endWeek"?: number }): Promise<any> {
    return this._request("GET", "/stats/season", { params });
  }

  /** Advanced team metrics by season */
  getAdvancedTeamSeasonStats(params: { "year"?: number; "team"?: string; "excludeGarbageTime"?: boolean; "startWeek"?: number; "endWeek"?: number }): Promise<any> {
    return this._request("GET", "/stats/season/advanced", { params });
  }

  /** Team talent composite rankings */
  getTalent(params: { "year"?: number }): Promise<any> {
    return this._request("GET", "/talent", { params });
  }

  /** Team information */
  getTeams(params: { "conference"?: string }): Promise<any> {
    return this._request("GET", "/teams", { params });
  }

  /** FBS team list */
  getFbsTeams(params: { "year"?: number }): Promise<any> {
    return this._request("GET", "/teams/fbs", { params });
  }

  /** Team matchup history */
  getTeamMatchup(params: { "team1": string; "team2": string; "minYear"?: number; "maxYear"?: number }): Promise<any> {
    return this._request("GET", "/teams/matchup", { params });
  }

  /** Arena and venue information */
  getVenues(): Promise<any> {
    return this._request("GET", "/venues", {});
  }
}

export default CollegeFootballData;