Guides
Start typing to search…

SportsStack API Trial Guide

SportsStack API Trial Guide

Get started with SportsStack's Unified Sports API in minutes. This guide walks you through the core endpoints with interactive examples you can test right away.

🏁

Quick Start

Ready to dive in? You'll need your API key and a few minutes to explore the most powerful sports data platform.

Authentication

All API requests require authentication via the Authorization header:

Authorization: Bearer YOUR_API_KEY_HERE
🔑

Get Your API Key

Contact our team to get your trial API key and start exploring immediately.

Base URL

All API calls are made to:

https://api.sportsstack.io/api/v1

⚠️ Trial API Caveats

📋

Demo Data Notice

What You're Exploring: This trial environment uses representative demo data designed to showcase SportsStack's structure, capabilities, and data format. You'll see realistic responses that demonstrate exactly how our unified sports data platform works.

What to Expect:

  • Demo Data: The data you see is for demonstration purposes and may not reflect current real-world sports information
  • Response Times: Some requests may take slightly longer than production performance due to demo environment limitations
  • Data Freshness: Information may not be up-to-date compared to live sports events
  • Rate Limits: Trial accounts have different rate limiting than production accounts

Production Reality: Once your organization is set up with production API keys, you'll experience:

  • Real-time Data: Live scores, odds, and statistics updating in real-time
  • Production Performance: Optimized response times and enhanced reliability
  • Current Information: Up-to-the-minute sports data from all major providers
  • Full Rate Limits: Higher throughput limits designed for production applications

The structure, endpoints, and response formats you see here are identical to production - this trial gives you the perfect foundation to build and test your integration!

🏀 Step 1: Explore Available Sports & Leagues

Start by discovering what sports and leagues are available in our platform.

List All Sports

curl -X GET "https://api.sportsstack.io/api/v1/sports" \
  -H "Authorization: Bearer YOUR_API_KEY"
const response = await fetch('https://api.sportsstack.io/api/v1/sports', {
  headers: {
    'Authorization': 'Bearer YOUR_API_KEY'
  }
});
const sports = await response.json();
console.log(sports);
import requests

headers = {
    'Authorization': 'Bearer YOUR_API_KEY'
}

response = requests.get('https://api.sportsstack.io/api/v1/sports', headers=headers)
sports = response.json()
print(sports)

Example Response:

{
  "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"
    }
  ]
}

List Leagues for a Sport

curl -X GET "https://api.sportsstack.io/api/v1/leagues?sport_id=4af4c296-6fbc-4705-8660-3b587c252e16" \
  -H "Authorization: Bearer YOUR_API_KEY"
const sportId = '4af4c296-6fbc-4705-8660-3b587c252e16';
const response = await fetch(`https://api.sportsstack.io/api/v1/leagues?sport_id=${sportId}`, {
  headers: {
    'Authorization': 'Bearer YOUR_API_KEY'
  }
});
const leagues = await response.json();
sport_id = '4af4c296-6fbc-4705-8660-3b587c252e16'
response = requests.get(f'https://api.sportsstack.io/api/v1/leagues?sport_id={sport_id}', headers=headers)
leagues = response.json()

Example Response:

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

👥 Step 2: Discover Teams & Players

Now explore the teams and players in your chosen league.

List Teams in a League

curl -X GET "https://api.sportsstack.io/api/v1/teams?league_id=8019d4db-7854-4542-b4af-7265d4b57105" \
  -H "Authorization: Bearer YOUR_API_KEY"
const leagueId = '8019d4db-7854-4542-b4af-7265d4b57105';
const response = await fetch(`https://api.sportsstack.io/api/v1/teams?league_id=${leagueId}`, {
  headers: {
    'Authorization': 'Bearer YOUR_API_KEY'
  }
});
const teams = await response.json();
league_id = '8019d4db-7854-4542-b4af-7265d4b57105'
response = requests.get(f'https://api.sportsstack.io/api/v1/teams?league_id={league_id}', headers=headers)
teams = response.json()

List Players in a League

curl -X GET "https://api.sportsstack.io/api/v1/players?league_id=8019d4db-7854-4542-b4af-7265d4b57105&limit=10" \
  -H "Authorization: Bearer YOUR_API_KEY"
const response = await fetch(`https://api.sportsstack.io/api/v1/players?league_id=${leagueId}&limit=10`, {
  headers: {
    'Authorization': 'Bearer YOUR_API_KEY'
  }
});
const players = await response.json();
response = requests.get(f'https://api.sportsstack.io/api/v1/players?league_id={league_id}&limit=10', headers=headers)
players = response.json()
💡

Pro Tip: Common Model IDs

Notice the common_model_id in every response? This is SportsStack's secret sauce - a unified identifier that connects the same entity across all data providers. Use these IDs to link players, teams, stats, and betting data together!

📅 Step 3: Find Events (Games)

Discover upcoming and past games in your league.

List Recent Events

curl -X GET "https://api.sportsstack.io/api/v1/events?league_id=8019d4db-7854-4542-b4af-7265d4b57105&season_year=2024&limit=5" \
  -H "Authorization: Bearer YOUR_API_KEY"
const response = await fetch(`https://api.sportsstack.io/api/v1/events?league_id=${leagueId}&season_year=2024&limit=5`, {
  headers: {
    'Authorization': 'Bearer YOUR_API_KEY'
  }
});
const events = await response.json();
response = requests.get(f'https://api.sportsstack.io/api/v1/events?league_id={league_id}&season_year=2024&limit=5', headers=headers)
events = response.json()

Get Live Event with Scoreboard

curl -X GET "https://api.sportsstack.io/api/v1/events/EVENT_ID?include_scoreboard=true" \
  -H "Authorization: Bearer YOUR_API_KEY"
const eventId = 'EVENT_ID_FROM_PREVIOUS_CALL';
const response = await fetch(`https://api.sportsstack.io/api/v1/events/${eventId}?include_scoreboard=true`, {
  headers: {
    'Authorization': 'Bearer YOUR_API_KEY'
  }
});
const liveEvent = await response.json();
event_id = 'EVENT_ID_FROM_PREVIOUS_CALL'
response = requests.get(f'https://api.sportsstack.io/api/v1/events/{event_id}?include_scoreboard=true', headers=headers)
live_event = response.json()

Example Response:

{
  "data": {
    "common_model_id": "4af4c296-6fbc-4705-8660-3b587c252e16",
    "status": "in_progress",
    "participants": [
      {
        "id": "e2790078-ec3a-4c45-8dc4-5cf173960b2b",
        "type": "team",
        "is_home": true,
        "points": 98,
        "abbreviation": "LAL"
      },
      {
        "id": "f3890179-fd4b-5d56-9ef5-6df274070c3c",
        "type": "team", 
        "is_home": false,
        "points": 95,
        "abbreviation": "GSW"
      }
    ],
    "scoreboard": {
      "period": 4,
      "time_remaining": "2:45"
    }
  }
}

📊 Step 4: Access Player & Team Statistics

Dive into the performance data that powers sports analytics.

🔑

Trial Event ID for Testing

Use this event ID for all event statistics examples:
Event ID: c45d95b2-c157-4106-ab1c-03d277c8da15

Get Player Stats from a Game

curl -X GET "https://api.sportsstack.io/api/v1/event-stats?event_id=c45d95b2-c157-4106-ab1c-03d277c8da15&for_entity_type=player&limit=5" \
  -H "Authorization: Bearer YOUR_API_KEY"
const eventId = 'c45d95b2-c157-4106-ab1c-03d277c8da15';
const response = await fetch(`https://api.sportsstack.io/api/v1/event-stats?event_id=${eventId}&for_entity_type=player&limit=5`, {
  headers: {
    'Authorization': 'Bearer YOUR_API_KEY'
  }
});
const playerStats = await response.json();
event_id = 'c45d95b2-c157-4106-ab1c-03d277c8da15'
response = requests.get(f'https://api.sportsstack.io/api/v1/event-stats?event_id={event_id}&for_entity_type=player&limit=5', headers=headers)
player_stats = response.json()

Get Season Stats for a Player

curl -X GET "https://api.sportsstack.io/api/v1/seasons/2024/season-stats?for_entity_type=player&for_entity_id=Cadence&league_id=8019d4db-7854-4542-b4af-7265d4b57105" \
  -H "Authorization: Bearer YOUR_API_KEY"
const playerId = 'Cadence';
const response = await fetch(`https://api.sportsstack.io/api/v1/seasons/2024/season-stats?for_entity_type=player&for_entity_id=${playerId}&league_id=${leagueId}`, {
  headers: {
    'Authorization': 'Bearer YOUR_API_KEY'
  }
});
const seasonStats = await response.json();
player_id = 'Cadence'
response = requests.get(f'https://api.sportsstack.io/api/v1/seasons/2024/season-stats?for_entity_type=player&for_entity_id={player_id}&league_id={league_id}', headers=headers)
season_stats = response.json()

🏈 Step 5: Access Play-by-Play Data (Optional)

Dive into detailed game actions and player-level play statistics.

🔑

Trial Event ID for Play Data

Use this event ID for all play-by-play examples:
Event ID: 83961740-2e01-4c52-86fd-fe7a645f5225

Get Game Plays

curl -X GET "https://api.sportsstack.io/api/v1/events/83961740-2e01-4c52-86fd-fe7a645f5225/plays?limit=10" \
  -H "Authorization: Bearer YOUR_API_KEY"
const eventId = '83961740-2e01-4c52-86fd-fe7a645f5225';
const response = await fetch(`https://api.sportsstack.io/api/v1/events/${eventId}/plays?limit=10`, {
  headers: {
    'Authorization': 'Bearer YOUR_API_KEY'
  }
});
const plays = await response.json();
event_id = '83961740-2e01-4c52-86fd-fe7a645f5225'
response = requests.get(f'https://api.sportsstack.io/api/v1/events/{event_id}/plays?limit=10', headers=headers)
plays = response.json()

Get Play-Level Statistics

curl -X GET "https://api.sportsstack.io/api/v1/events/83961740-2e01-4c52-86fd-fe7a645f5225/play-stats?limit=10" \
  -H "Authorization: Bearer YOUR_API_KEY"
const response = await fetch(`https://api.sportsstack.io/api/v1/events/${eventId}/play-stats?limit=10`, {
  headers: {
    'Authorization': 'Bearer YOUR_API_KEY'
  }
});
const playStats = await response.json();
response = requests.get(f'https://api.sportsstack.io/api/v1/events/{event_id}/play-stats?limit=10', headers=headers)
play_stats = response.json()
🎮

Perfect for Fantasy & Betting

Play-by-play data enables advanced analytics like target share analysis, red zone efficiency, and situational performance metrics.

🎯 Step 6: Explore Betting Markets (Optional)

See live betting odds and markets for events.

🔑

Trial Event ID for Betting Data

Use this event ID for all play-by-play examples:
Event ID: fbb78bef-fc71-40a8-94d5-ac356e79d0ac


Get Betting Markets for an Event

curl -X GET "https://api.sportsstack.io/api/v1/markets?event_id=EVENT_ID&include_outcomes_and_odds=true&limit=3" \
  -H "Authorization: Bearer YOUR_API_KEY"
const response = await fetch(`https://api.sportsstack.io/api/v1/markets?event_id=${eventId}&include_outcomes_and_odds=true&limit=3`, {
  headers: {
    'Authorization': 'Bearer YOUR_API_KEY'
  }
});
const bettingMarkets = await response.json();
response = requests.get(f'https://api.sportsstack.io/api/v1/markets?event_id={event_id}&include_outcomes_and_odds=true&limit=3', headers=headers)
betting_markets = response.json()

Example Response:

{
  "data": [
    {
      "common_model_id": "123e4567-e89b-12d3-a456-426614174010",
      "name": "Game Winner",
      "market_type": "h2h",
      "event_id": "4af4c296-6fbc-4705-8660-3b587c252e16",
      "outcomes": [
        {
          "name": "Los Angeles Lakers",
          "odds": [
            {
              "sportsbook": "draftkings",
              "price": -110,
              "price_type": "american"
            },
            {
              "sportsbook": "fanduel",
              "price": -105,
              "price_type": "american"
            }
          ]
        }
      ]
    }
  ]
}

🔍 Step 7: Understanding Data Relationships

Learn how to connect data across different providers using our mapping system.

Find All Provider IDs for an Entity

curl -X GET "https://api.sportsstack.io/api/v1/mappings?entity_type=player&common_model_id=PLAYER_ID&include_all_mappings=true" \
  -H "Authorization: Bearer YOUR_API_KEY"
const response = await fetch(`https://api.sportsstack.io/api/v1/mappings?entity_type=player&common_model_id=${playerId}&include_all_mappings=true`, {
  headers: {
    'Authorization': 'Bearer YOUR_API_KEY'
  }
});
const mappings = await response.json();
response = requests.get(f'https://api.sportsstack.io/api/v1/mappings?entity_type=player&common_model_id={player_id}&include_all_mappings=true', headers=headers)
mappings = response.json()
🔗

Data Lineage Made Easy

These mappings show you how the same player/team/event appears across different data providers (SportRadar, FTN, ESPN, etc.). Perfect for debugging and understanding data relationships!

🚀 Next Steps

Congratulations! You've successfully explored the core SportsStack API endpoints. Here's what you can do next:

Integration Paths

  1. Build a Sports App: Use teams, players, and events to create roster management or fan engagement apps
  2. Analytics Dashboard: Combine event stats and season stats for performance analysis
  3. Betting Platform: Leverage our real-time odds and market data for betting applications
  4. Fantasy Sports: Use player stats and projections for fantasy league management

Advanced Features

  • News & Insights: Get AI-generated content about players and teams
  • Injury Reports: Stay updated on player availability (FTN data)
  • Play-by-Play: Access detailed game actions (NFL via FTN)
  • Historical Data: Query past seasons and events for trend analysis

Production Considerations

  • Rate Limits: Cache static data (teams, players) for 24+ hours
  • Live Data: Poll every 30-60 seconds for live scores during games
  • Betting Data: Update odds every 10-30 seconds for real-time betting
  • Authentication: Always use server-to-server calls, never expose API keys in frontend
📚

Complete Documentation

Ready to dive deeper? Check out our full integration guide for comprehensive API documentation, advanced use cases, and production best practices.

🆘 Need Help?

  • API Documentation: Browse our complete OpenAPI specification at /openapi
  • Support: Contact our team for integration assistance
  • Community: Join our developer community for tips and best practices
🎉

Welcome to SportsStack!

You're now ready to build amazing sports applications with the most comprehensive unified sports data platform. Happy coding!

Updated about 23 hours ago