Guides
Start typing to search…

SportsStack Integration Guide

A comprehensive guide for developers integrating with the SportsStack Unified Sports API

Quick Start Checklist

✅ Setup

  • Obtain API key from SportsStack
  • Configure Authorization: Bearer <api_key> header
  • Set up backend server integration (never frontend)

✅ Foundation Data (Cache 24+ hours)

  • Load sports: GET /api/v1/sports
  • Load leagues: GET /api/v1/leagues
  • Load teams: GET /api/v1/teams?league_id=<league>
  • Load players: GET /api/v1/players?league_id=<league>

✅ Event Data (Cache 4+ hours, live data 30-60s)

  • Load schedule: GET /api/v1/events?league_id=<league>&season_year=2024
  • Live scoreboards: GET /api/v1/events/<id>?include_scoreboard=true

✅ Statistics (Cache based on type)

  • Event stats: GET /api/v1/events/<id>/event-stats
  • Season stats: GET /api/v1/seasons/2024/season-stats
  • Understand projections vs actuals

✅ Enhanced Features

  • News: GET /api/v1/news/league/<league_id>
  • Injuries: GET /api/v1/injuries?league_id=<league> (FTN only)
  • Plays: GET /api/v1/events/<id>/plays (FTN only)

✅ Betting (Cache 10-30s for live odds)

  • Markets: GET /api/v1/markets?event_id=<event>&include_outcomes_and_odds=true
  • Use combined endpoints for efficiency

✅ Debugging

  • Mappings: GET /api/v1/mappings?entity_type=player&common_model_id=<id>
  • Understand Common Model ID system

Need Help?

  • Review our API documentation at /openapi
  • Contact support for integration assistance
  • Check rate limits and caching recommendations above

Integration Guide

Backend Server Integration

⚠️ Important: Server-to-Server Only
SportsStack APIs are designed for backend server integration only. Never call our APIs directly from frontend applications (web, mobile) due to:

  • API key security
  • Rate limiting and quota management
  • Large response payloads optimized for backend processing
  • Real-time data that requires server-side caching strategies

Reach out if there are use-cases where you would like to call from the client applications

Authentication

Include your API key in the Authorization header:

Authorization: Bearer your_api_key_here

Rate Limiting Best Practices

  • Base Data (Players/Teams/Events): Cache for 24+ hours, refresh daily
  • Live Event Data: Poll every 30-60* seconds during live games only
  • Historical Stats: Cache indefinitely, refresh only when corrections needed
  • Markets/Odds: Poll every 10-30 seconds for live betting scenarios
  • News: Poll every 15-30 minutes

Response Caching Strategy

// Recommended caching approach
const cacheStrategy = {
  // Static/Reference Data (cache long-term)
  sports: '7 days',
  leagues: '7 days', 
  players: '24 hours',    // Updates for trades/signings
  teams: '24 hours',      // Updates for roster changes
  
  // Event Data (cache medium-term)
  scheduledEvents: '4 hours',  // Schedule changes possible
  completedEvents: '∞',        // Never changes once final
  
  // Live Data (cache short-term)
  liveEventScoreboard: '30 seconds',
  activeMarkets: '30 seconds',
  currentOdds: '10 seconds',
  
  // Stats Data (cache based on type)
  seasonStats: '4 hours',      // Updates throughout season
  completedEventStats: '∞',    // Never changes once final
  projections: '2 hours',      // Models update regularly
  
  // News and Insights
  news: '30 minutes'
};

Common Model ID

The Common Model ID is the cornerstone of SportsStack's data normalization system. It's a UUID that uniquely identifies the same real-world entity across all data providers in our platform.

Example:

{
  "common_model_id": "f1798a7e-4832-4a2c-8cb6-60d5afcb3d41",
  "full_name": "LeBron James"
}

This same common_model_id will appear in:

  • Player records from SportRadar
  • Player statistics from FTN
  • Player injury reports from ESPN
  • Player news and insights
  • Player prop betting markets
  • Player performance analytics

Benefits:

  • Data Aggregation: Easily combine data from multiple sources about the same entity
  • Relationship Mapping: Connect players to teams, events, statistics, and markets
  • Historical Continuity: Track entities through trades, team changes, and career progression
  • Cross-Reference: Link betting markets to specific players/teams with confidence

Core Entity Types

Our data model centers around key sports entities that form the foundation of all sports data:

Sports / Leagues

Sports and Leagues form the organizational hierarchy of all sports data. Start here to understand what data is available.

Available Sports

GET /api/v1/sports

Returns all sports supported by SportsStack:

{
  "data": [
    {
      "common_model_id": "4af4c296-6fbc-4705-8660-3b587c252e16",
      "name": "basketball",
      "abbreviation": "bball"
    },
    {
      "common_model_id": "58e8c89b-72f8-4427-adbc-10f193c9b462", 
      "name": "football",
      "abbreviation": "nfl"
    }
  ]
}

Available Leagues

GET /api/v1/leagues

Filter by sport:

GET /api/v1/leagues?sport_id=4af4c296-6fbc-4705-8660-3b587c252e16

Returns leagues within a sport:

{
  "data": [
    {
      "common_model_id": "8019d4db-7854-4542-b4af-7265d4b57105",
      "name": "National Basketball Association", 
      "abbreviation": "NBA",
      "sport_id": "4af4c296-6fbc-4705-8660-3b587c252e16"
    }
  ]
}

Call Frequency: Cache for 7 days (sports and leagues rarely change)

Base Data - Players / Teams / Events

These are the foundational entities you'll use to build your sports application. Load these first and cache aggressively.

Players

List Players

GET /api/v1/players

Filter Options:

  • league_id - Players in specific league
  • team_id - Players on specific team
  • position - Players at specific position
  • name - Search by player name
GET /api/v1/players?league_id=8019d4db-7854-4542-b4af-7265d4b57105&team_id=e2790078-ec3a-4c45-8dc4-5cf173960b2b

Individual Player

GET /api/v1/players/f1798a7e-4832-4a2c-8cb6-60d5afcb3d41

Call Frequency:

  • Full player list: Daily (for roster updates, trades)

Teams

List Teams

GET /api/v1/teams

Filter Options:

  • league_id - Teams in specific league
  • name - Search by team name
  • abbreviation - Filter by team abbreviation
GET /api/v1/teams?league_id=8019d4db-7854-4542-b4af-7265d4b57105

Individual Team

GET /api/v1/teams/e2790078-ec3a-4c45-8dc4-5cf173960b2b

Call Frequency: Daily (teams rarely change, but roster updates happen)

Events

Events represent games, matches, or competitions. They are the central entity connecting teams, players, statistics, and betting markets.

List Events

GET /api/v1/events

Filter Options:

  • league_id - Events in specific league
  • season_year - Events in specific season
  • week - Events in specific week (for weekly sports)
  • season_type - PRE (preseason), REG (regular), POST (playoffs)
  • status - scheduled, in_progress, completed, cancelled
  • date_range - Events within date range
GET /api/v1/events?league_id=8019d4db-7854-4542-b4af-7265d4b57105&season_year=2024&week=12

Individual Event

GET /api/v1/events/4af4c296-6fbc-4705-8660-3b587c252e16

Event with Live Scoreboard

GET /api/v1/events/4af4c296-6fbc-4705-8660-3b587c252e16?include_scoreboard=true

Event Participants Data Structure

The participants field in events uses a standardized structure to represent teams, players, or other entities competing in the event. Understanding this structure is crucial for building sports applications.

Participant Structure:

{
  "id": "01234567-89ab-cdef-0123-456789abcdef",  // Common Model ID
  "type": "team",                                // Participant type
  "is_home": true,                               // Home indicator 
  "points": 21,                                  // Current score
  "seed": 4,                                     // Tournament seed
  "record": "10-12",                             // Record
  "abbreviation": "LAL",                         // Display abbreviation
  "name": "Los Angeles Lakers"                   // Display name
}

Sport-Specific Examples:

Team Sports (NFL, NBA, NHL):

{
  "participants": [
    {
      "id": "e2790078-ec3a-4c45-8dc4-5cf173960b2b",
      "source_id": "sr:competitor:4387",
      "type": "team", 
      "is_home": true,
      "points": 28,
      "abbreviation": "LAL"
    },
    {
      "id": "f3890179-fd4b-5d56-9ef5-6df274070c3c", 
      "source_id": "sr:competitor:4388",
      "type": "team",
      "is_home": false, 
      "points": 21,
      "abbreviation": "GSW"
    }
  ]
}

Individual Sports (Golf, Tennis):

{
  "participants": [
    {
      "id": "a1234567-b890-c123-d456-e78901234567",
      "source_id": "sr:player:12345", 
      "type": "player",
      "points": -12,    // Golf: under par, Tennis: match score
      "abbreviation": null
    },
    {
      "id": "b2345678-c901-d234-e567-f89012345678",
      "source_id": "sr:player:67890",
      "type": "player", 
      "points": -8,
      "abbreviation": null
    }
  ]
}

Tournament Events (March Madness):

{
  "participants": [
    {
      "id": "c3456789-d012-e345-f678-901234567890",
      "source_id": "sr:competitor:5001",
      "type": "team",
      "is_home": false,  // Neutral site tournament
      "points": 72,
      "seed": 1,         // #1 seed
      "abbreviation": "DUKE"
    },
    {
      "id": "d4567890-e123-f456-0789-012345678901", 
      "source_id": "sr:competitor:5002",
      "type": "team",
      "is_home": false,
      "points": 68,
      "seed": 16,        // #16 seed
      "abbreviation": "UMBC"
    }
  ]
}

Key Implementation Notes:

  1. Common Model ID Resolution: Always use the id field (Common Model ID) to link participants to other entities like statistics, injuries, and betting markets.

  2. Home Field Advantage: Use is_home boolean rather than string values:

    • true = home team/player
    • false = away team/player
    • null = neutral site or not applicable

  3. Live Score Updates: The points field updates in real-time during live events and reflects final scores for completed events.

  4. Multi-Sport Consistency: The same structure works across all sports - teams for team sports, individual players for individual competitions.

  5. Data Relationships: Use participant id values to query related data:

    # Get player stats for event participant
GET /api/v1/event-stats?event_id={event_id}&for_entity_id={participant_id}

# Get team information
GET /api/v1/teams/{participant_id}

# Get player prop markets
GET /api/v1/markets?event_id={event_id}&player_id={participant_id}

Call Frequency:

  • Scheduled Events: 4 hours (schedule changes possible)
  • Live Events: 30-60 seconds (during games only)
  • Completed Events: Cache permanently (never changes)

Mapping APIs

The Mapping API provides visibility into how external provider IDs map to our Common Model IDs. This is crucial for debugging data issues and understanding data lineage.

List Mappings

GET /api/v1/mappings

Filter Options:

  • entity_type - player, team, event, league, market
  • integration - sportradar, ftn, espn, draftkings
  • league - nfl, nba, mlb, nhl
  • common_model_id - Find all provider IDs for a specific entity
  • source_id - Find which entity a provider ID maps to
GET /api/v1/mappings?entity_type=player&integration=sportradar&league=nfl&common_model_id=f1798a7e-4832-4a2c-8cb6-60d5afcb3d41

Individual Mapping with All Providers

GET /api/v1/mappings/49306211-7b48-4b5e-88e9-a4190189dbea?include_all_mappings=true

Returns all known provider mappings for an entity:

{
  "data": {
    "common_model_id": "f1798a7e-4832-4a2c-8cb6-60d5afcb3d41",
    "entity_type": "player",
    "all_mappings": [
      {"integration": "sportradar", "source_id": "sr:player:123456"},
      {"integration": "ftn", "source_id": "FTN_45678"},
      {"integration": "espn", "source_id": "ESPN_987654"}
    ]
  }
}

Call Frequency: Daily (mappings change rarely, but new ones are added regularly)

Event Stats / Season Stats

Statistics are the core of sports analytics, available at both individual event and season aggregate levels.

Event-Scoped Statistics

Statistics for specific players/teams within individual events (games).

List Event Stats

GET /api/v1/event-stats

Event Stats for Specific Event

GET /api/v1/events/4af4c296-6fbc-4705-8660-3b587c252e16/event-stats

Filter Options:

  • event_id - Stats for specific event
  • for_entity_id - Stats for specific player/team
  • for_entity_type - player or team
  • source - sportradar, ftn, espn, fantasylabs
  • is_projection - true/false

Player Stats from Specific Event

GET /api/v1/event-stats?event_id=4af4c296-6fbc-4705-8660-3b587c252e16&for_entity_id=f1798a7e-4832-4a2c-8cb6-60d5afcb3d41&source=sportradar&is_projection=false

Season-Scoped Statistics

Aggregated statistics across all events within a season.

GET /api/v1/seasons/2024/season-stats

Filter Options:

  • for_entity_type - player or team
  • for_entity_id - Specific player/team
  • league_id - Specific league
  • season_type - PRE, REG, POST
  • source - Data provider
  • is_projection - true/false

Player Season Stats

GET /api/v1/seasons/2024/season-stats?for_entity_type=player&for_entity_id=f1798a7e-4832-4a2c-8cb6-60d5afcb3d41&league_id=8019d4db-7854-4542-b4af-7265d4b57105&source=sportradar

Projections vs Actuals

All statistics include an is_projection field that distinguishes between:

Actuals (is_projection: false):

  • Real game results from official scorekeepers
  • Post-game verified statistics
  • Historical performance data
  • Source: Typically SportRadar (official data)

Projections (is_projection: true):

  • Pre-game performance forecasts
  • Machine learning model predictions
  • Expert analyst projections
  • Source: Typically FTN, FantasyLabs, Awesemo

Example Usage:

// Get actual player performance from last game
const actuals = await fetch('/api/v1/event-stats?' + new URLSearchParams({
  event_id: 'last_game_id',
  for_entity_id: 'player_id', 
  is_projection: false,
  source: 'sportradar'
}));

// Get projections for upcoming game  
const projections = await fetch('/api/v1/event-stats?' + new URLSearchParams({
  event_id: 'upcoming_game_id',
  for_entity_id: 'player_id',
  is_projection: true, 
  source: 'ftn'
}));

Call Frequency:

  • Actual Stats: Cache permanently once game is final
  • Projections: 2-4 hours (models update regularly)

News

AI-generated insights and analysis about players, teams, events, and leagues.

News by League

GET /api/v1/news/league/8019d4db-7854-4542-b4af-7265d4b57105

News by Entity

GET /api/v1/news/player/f1798a7e-4832-4a2c-8cb6-60d5afcb3d41
GET /api/v1/news/team/e2790078-ec3a-4c45-8dc4-5cf173960b2b  
GET /api/v1/news/event/4af4c296-6fbc-4705-8660-3b587c252e16

News Content Types:

  • headline: Summary of the main story
  • summary: 2-3 sentence overview
  • analysis: Detailed breakdown with deeper insights
  • betting_analysis: Betting market focused analysis
  • tags: Content categorization for filtering

Call Frequency: 15-30 minutes (news updates regularly throughout the day)

Plays

⚠️ Data Availability: FTN Only
Play-by-play data is currently only available from FTN provider and covers NFL games.

Event Plays

GET /api/v1/events/4af4c296-6fbc-4705-8660-3b587c252e16/plays

Filter Options:

  • period - Specific quarter/period
  • play_type - pass, run, penalty, etc.

Player Play Stats

Individual player statistics within specific plays:

GET /api/v1/players/f1798a7e-4832-4a2c-8cb6-60d5afcb3d41/play-stats
GET /api/v1/events/4af4c296-6fbc-4705-8660-3b587c252e16/play-stats

Call Frequency:

  • Live Games: Every 30 seconds during games
  • Completed Games: Cache permanently

Injuries

⚠️ Data Availability: FTN Only
Injury reports are currently only available from FTN provider.

GET /api/v1/injuries

Filter Options:

  • league_id - Injuries in specific league
  • player_id - Injuries for specific player
  • status - out, questionable, doubtful, ir, suspended, pup

Injury Status Definitions:

  • out: Definitely will not play
  • questionable: Uncertain availability, game-time decision
  • doubtful: Unlikely to play but not ruled out
  • ir: Injured Reserve, extended absence
  • suspended: League disciplinary action
  • pup: Physically Unable to Perform list

Call Frequency: 2-4 hours (injury reports update frequently, especially during season)

Markets / Outcomes / Odds

The betting module provides comprehensive sports betting market data with real-time odds from multiple sportsbooks.

Terminology Overview

Understanding the relationship between Markets, Outcomes, and Odds:

Market = A betting opportunity/question

  • "Who will win the game?" (Moneyline)
  • "Will the total points be over/under 215.5?" (Totals)
  • "How many passing yards will Josh Allen have?" (Player Props)

Outcome = A specific answer to the market question

  • "Buffalo Bills" (for moneyline market)
  • "Over 215.5" (for totals market)
  • "Over 275.5 yards" (for player prop market)

Odds = The price/probability for that outcome from each sportsbook

  • DraftKings: -110
  • FanDuel: -105
  • BetMGM: -115

Market Data Structure

List Markets

GET /api/v1/markets

Filter Options:

  • event_id - Markets for specific event
  • league_id - Markets for specific league
  • market_type - h2h, spreads, totals, player_props
  • is_main - true/false (main vs alternate lines)
  • is_future - true/false (season-long vs game-specific)
  • status - active, suspended, settled

Event-Specific Markets

GET /api/v1/markets?event_id=4af4c296-6fbc-4705-8660-3b587c252e16&is_main=true

Outcome Data

List Outcomes

GET /api/v1/outcomes

Filter Options:

  • market_id - Outcomes for specific market
  • event_id - All outcomes for an event
  • team_id - Outcomes involving specific team
  • player_id - Outcomes involving specific player (props)
  • is_alternate_line - true/false

Current Odds

List Odds

GET /api/v1/odds

Filter Options:

  • outcome_id - Odds for specific outcome
  • sportsbook - draftkings, fanduel, betmgm, etc.
  • price_type - decimal, american

Grabbing Combined Markets + Odds

🚀 Pro Tip: Use Include Parameters

Instead of making separate API calls for markets, outcomes, and odds, use the include_outcomes_and_odds parameter to get everything in one request:

Markets with Outcomes and Odds

GET /api/v1/markets?event_id=4af4c296-6fbc-4705-8660-3b587c252e16&include_outcomes_and_odds=true

Individual Market with Complete Data

GET /api/v1/markets/123e4567-e89b-12d3-a456-426614174010?include_outcomes_and_odds=true

Example Response:

{
  "data": {
    "common_model_id": "123e4567-e89b-12d3-a456-426614174010",
    "name": "Game Winner",
    "market_type": "h2h",
    "is_main": true,
    "event_id": "4af4c296-6fbc-4705-8660-3b587c252e16",
    "outcomes": [
      {
        "common_model_id": "outcome-1",
        "name": "Buffalo Bills",
        "selection": "Buffalo Bills",
        "odds": [
          {
            "sportsbook": "draftkings",
            "price": -110,
            "price_type": "american",
            "timestamp": "2024-01-15T15:30:00Z"
          },
          {
            "sportsbook": "fanduel", 
            "price": -105,
            "price_type": "american",
            "timestamp": "2024-01-15T15:29:45Z"
          }
        ]
      },
      {
        "common_model_id": "outcome-2",
        "name": "Miami Dolphins",
        "selection": "Miami Dolphins",
        "odds": [
          {
            "sportsbook": "draftkings",
            "price": -110,
            "price_type": "american", 
            "timestamp": "2024-01-15T15:30:00Z"
          },
          {
            "sportsbook": "fanduel",
            "price": -115,
            "price_type": "american",
            "timestamp": "2024-01-15T15:29:45Z"
          }
        ]
      }
    ]
  }
}

Performance Benefits:

  • Single Request: Get complete betting data in one API call
  • Reduced Latency: Eliminate multiple round trips
  • Atomic Data: Guaranteed consistency across markets/outcomes/odds
  • Rate Limit Friendly: Uses fewer API quota

Call Frequency:

  • Live Betting: 10-30* seconds during events
  • Pre-Game: 5-15 minutes
  • Futures Markets: 1-4 hours

Updated 9 days ago