API Reference

The StatsGuy REST API lets you pull game, season, team, and player stats programmatically. Authenticate using an X-API-Key header with a key generated in your dashboard.

Authentication

All API requests require an X-API-Key header:

curl https://statsguy.clickingspree.com/api/v1/stats/game/GAME_ID \
  -H "X-API-Key: sg_your_key_here"

API keys are scoped to your account. Generate and revoke keys from Dashboard → API Keys.

Base URL

https://statsguy.clickingspree.com/api/v1

Rate Limits

500 requests per 15-minute window per API key.

Endpoints — Stats

GET

https://statsguy.clickingspree.com/api/v1/stats/game/:gameId

Returns team stats and player stats for a single completed or in-progress game.

Example Response

{
  "game": { "id": "...", "gameDate": "2025-10-04", "status": "final",
             "finalHomeScore": 28, "finalAwayScore": 14, ... },
  "teamStats": [
    { "team": { "abbreviation": "WSW" },
      "passYards": 312, "rushYards": 145, "totalYards": 457, ... }
  ],
  "playerStats": [
    { "player": { "lastName": "Johnson", "firstName": "D.", "number": "5", "position": "QB" },
      "passAttempts": 28, "passCompletions": 19, "passYards": 247, "passTouchdowns": 3, ... }
  ]
}

GET

https://statsguy.clickingspree.com/api/v1/stats/season/:seasonId

Returns season-aggregate player stats across all final games in the season.

Example Response

{
  "season": { "id": "...", "name": "2025 Season", "year": 2025 },
  "playerStats": [
    { "playerId": "...", "teamId": "...",
      "_sum": { "passYards": 2847, "passTouchdowns": 24, "rushYards": 312, ... } }
  ]
}

GET

https://statsguy.clickingspree.com/api/v1/stats/team/:teamId

Returns game-by-game team stats for all games a team has played.

Parameters

Name	Type	Required	Description
teamId	string (UUID)	yes	The team ID

Example Response

{
  "team": { "name": "Westside Warriors", "abbreviation": "WSW", ... },
  "stats": [
    { "game": { "gameDate": "2025-09-05", ... },
      "passYards": 280, "rushYards": 190, "totalPoints": 35, ... }
  ]
}

GET

https://statsguy.clickingspree.com/api/v1/stats/player/:playerId

Returns game-by-game stats for a single player.

Example Response

{
  "player": { "firstName": "Derek", "lastName": "Johnson", "number": "5", "position": "QB" },
  "stats": [
    { "game": { "gameDate": "2025-09-05", ... },
      "passAttempts": 32, "passCompletions": 21, "passYards": 289, ... }
  ]
}

GET

https://statsguy.clickingspree.com/api/v1/stats/leaders/:seasonId

Returns season stat leaders grouped by category — top passers, rushers, receivers, and defenders across all final games.

Example Response

{
  "passing": [
    { "playerId": "...", "playerName": "D. Johnson",
      "attempts": 198, "completions": 132, "yards": 2847,
      "touchdowns": 24, "interceptions": 6 }
  ],
  "rushing": [
    { "playerId": "...", "playerName": "M. Williams",
      "carries": 187, "yards": 1204, "touchdowns": 14 }
  ],
  "receiving": [
    { "playerId": "...", "playerName": "T. Davis",
      "receptions": 68, "yards": 1092, "touchdowns": 11 }
  ],
  "defense": [
    { "playerId": "...", "playerName": "J. Brown",
      "soloTackles": 62, "assistedTackles": 21,
      "totalTackles": 83, "sacks": 4.5 }
  ]
}

Endpoints — SpreeSports

These endpoints are designed for SpreeSports broadcast graphic integration. They return data pre-formatted for PlayerInfo, HeadToHead, and StatsPage graphic types.

GET

https://statsguy.clickingspree.com/api/v1/spree/game/:gameId

Full snapshot for a game — team stats, all player stats with formatted stat lines and career context, ready to cache in SpreeSports.

Example Response

{
  "gameId": "...",
  "homeTeam": { "id": "...", "name": "Westside Warriors", "abbreviation": "WSW" },
  "awayTeam": { "id": "...", "name": "Eastside Eagles", "abbreviation": "ESE" },
  "homeScore": 21, "awayScore": 14,
  "teamStats": { "home": { "totalYards": 412, "passYards": 268, ... }, "away": { ... } },
  "players": [
    { "playerId": "...", "name": "D. Johnson", "number": "5", "position": "QB",
      "teamId": "...", "stats": ["19/28 247 YDS 3 TD", "Career (8G): 132/198 2847 YDS 24 TD"],
      "game": { "passAttempts": 28, "passYards": 247, ... } }
  ],
  "updatedAt": "2025-10-04T21:34:12.000Z"
}

GET

https://statsguy.clickingspree.com/api/v1/spree/game/:gameId/player/:playerId

Single player card with in-game and career stats. Returns PlayerInfoData shape for SpreeSports.

Example Response

{
  "name": "Derek Johnson", "number": "5", "position": "QB",
  "team": "Westside Warriors", "teamAbbreviation": "WSW",
  "yearClass": "Sr", "height": 75, "weight": 215, "hometown": "Tampa, FL",
  "gameStats": ["19/28 247 YDS 3 TD 0 INT"],
  "careerStats": ["8G 132/198 (66.7%) 2847 YDS 24 TD"],
  "rawGame": { "passAttempts": 28, "passYards": 247, ... },
  "rawCareer": { "passAttempts": 198, "passYards": 2847, ... }
}

GET

https://statsguy.clickingspree.com/api/v1/spree/game/:gameId/matchup/:position

Position-group head-to-head comparison. Returns HeadToHeadData shape. Position values: QB, RB, WR, TE, K, P, LB, DE, CB, S, etc.

Example Response

{
  "title": "QB Matchup",
  "homeTeam": "WSW", "awayTeam": "ESE",
  "homePlayers": ["#5 D. Johnson"],
  "awayPlayers": ["#12 M. Garcia"],
  "stats": [
    { "label": "COMP/ATT", "homeValue": "19/28", "awayValue": "14/24" },
    { "label": "COMP %",   "homeValue": "67.9%", "awayValue": "58.3%" },
    { "label": "PASS YDS", "homeValue": "247",   "awayValue": "189"   },
    { "label": "PASS TD",  "homeValue": "3",     "awayValue": "1"     },
    { "label": "INT",      "homeValue": "0",     "awayValue": "2"     }
  ]
}

GET

https://statsguy.clickingspree.com/api/v1/spree/game/:gameId/team-stats

Full team comparison for a game. Returns StatsPageData shape matching NFL broadcast layout.

Example Response

{
  "title": "Team Statistics",
  "homeTeam": "WSW", "awayTeam": "ESE",
  "stats": [
    { "label": "FIRST DOWNS",  "homeValue": "22",    "awayValue": "17"    },
    { "label": "TOTAL YARDS",  "homeValue": "412",   "awayValue": "298"   },
    { "label": "PASSING",      "homeValue": "268",   "awayValue": "189"   },
    { "label": "RUSHING",      "homeValue": "144",   "awayValue": "109"   },
    { "label": "TURNOVERS",    "homeValue": "0",     "awayValue": "2"     },
    { "label": "TIME OF POSS", "homeValue": "32:14", "awayValue": "27:46" },
    ...
  ]
}

Endpoints — Games

GET

https://statsguy.clickingspree.com/api/v1/games

List all games for your account, optionally filtered.

Parameters

Name	Type	Required	Description
seasonId	string	no	Filter by season
teamId	string	no	Filter to games involving a team
status	string	no	scheduled \| in_progress \| final

Example Response

[
  { "id": "...", "gameDate": "2025-10-04",
    "homeTeam": { "name": "Westside Warriors", "abbreviation": "WSW" },
    "awayTeam": { "name": "Eastside Eagles", "abbreviation": "ESE" },
    "finalHomeScore": 28, "finalAwayScore": 14, "status": "final" },
  ...
]

GET

https://statsguy.clickingspree.com/api/v1/games/:id/plays

Returns full play-by-play log for a game with all passing, rushing, and defensive details.

Example Response

[
  { "playNumber": 1, "quarter": 1, "gameClock": "12:00",
    "down": 1, "distance": 10, "yardLine": 25,
    "playType": "rush", "yardsGained": 6,
    "rushingPlay": { "rusher": { "lastName": "Williams", "number": "22" }, "yards": 6, ... } },
  ...
]

Error responses

// 401 — missing or invalid API key
{ "error": "Invalid API key" }

// 404 — resource not found
{ "error": "Game not found" }

// 429 — rate limit exceeded
{ "error": "Too many requests" }

Pagination

Endpoints that return lists currently return all matching records. Pagination support (cursor-based) is on the roadmap for season endpoints with large result sets.