The Gold Standard in Olympics Data Learn More
The Gold Standard in Olympics Data Learn More
Developer Portal

Sports Data API Integration Guide

If you're interested in learning more about our sports data products, please contact us for a custom quote.

At SportsDataIO, we've seen a lot of clients build out their applications using a variety of methods. As you know, with software development, there are many ways to build something right. The following guidelines are recommendations for integrating with our API. If you'd rather take a different approach, for whatever reason, then go for it!

Here we offer basic guidelines to begin your implementation. We assume you know what sports you are interested in, and that you will be storing our data in your own database so that you can work with it locally.

Basic Data Integration

The first step toward integrating with our feeds is to sync your sport’s basic data to your database. Basic data includes:

  • Timeframes
  • Venues & Stadiums
  • Teams
  • Roster & Squads
  • League Structure
  • Standings
  • Schedule

This data does not change very often, so you can refresh it every evening during off-hours. Plus, it forms the bedrock on which more advanced data relies. (For example, to interpret box scores and advanced statistical data, it helps to know the team and players in question first.)

SOCCER ONLY

For soccer, our API delivers data for 20+ competitions (leagues). So, it's a little bit of a different animal than the other APIs, which only provide data for a single league (NFL, MLB, NBA, NHL, etc).

  1. So, for soccer, you'll want to sync the competition (league) hierarchy first, which includes areas (i.e. countries/regions) (e.g. Europe, England, USA, etc).
  2. Once you have competition data synced to your database, we recommend syncing the competition details for any competitions that you plan to implement. This takes care of seasons, rounds (i.e. regular season, post season), teams w/ squads/rosters (for the current season), and the schedule/scores (for the current season).

Team Sports Other Than Soccer

Includes: NFL, MLB, NBA, NHL, CFB, CBB

For the team sports other than soccer, things are a bit more straightforward, because there is only one league covered per API. Please use the following steps to sync fixture data for these sports.

  1. Timeframes (NFL ONLY)
    Because the NFL is a weekly sport, dates aren't as useful as weeks for point-in-time context. The first step for NFL is to sync the timeframes to your database. Timeframes are equivalent to "Weeks" during the NFL season. They never change, but you will want to use the Timeframe API to determine what the current week is. This will allow you to dynamically pull team/player stats for the current week, by getting the current week from timeframe API, then passing that along to the other APIs.
    Learn more about NFL timeframes
  2. Teams
    Sync the team data every evening to ensure you have the latest team information.
  3. Schedule
    Sync the schedules once every hour to ensure you have the most up-to-date start times for games in your database. The schedule feed includes odds and weather (for NFL and MLB only).
  4. Standings
    Sync standings every evening or once every hour if you prefer a more up-to-date feed, particularly on gamedays.

Advanced Data Integration

Now that we have the foundations, we can load more advanced data, such as:

  • Box Scores
  • Projections
  • Starting Lineups

  1. Box Scores (includes player & team stats)
    Regardless of which package you have (post game, live, or realtime), you'll want to pull updated stats for the current date and previous date every hour or so. This is because we can occasionally issue corrections, so you'll want to ensure you refresh data for at least 24 hours after a game is over, but 48-72 hours is better. We'd recommend that each night/early morning, you pull any stat corrections, by syncing box score data for the past 3-4 days. This should be a relatively inexpensive process since it only runs once per day. Also, as you may know, the NFL can change their official stats several days after an event completes (mid-week corrections). These happen as late as the Friday after games are completed.

    To sync team & player stats for these team sports, we highly recommend using the Box Scores by Date API. The box scores includes all the data, such as Player Stats, Fantasy Defense Stats and Team Stats, as well as the info for the given game. Here are the links to the Box Scores By Date per league:
    API Docs
    NFL Box Scores by Week
    MLB Box Scores by Date
    NBA Box Scores by Date
    NHL Box Scores by Date
    CFB Box Scores by Week
    CBB Box Scores by Date
    Soccer Box Scores by Date (all competitions)
    Soccer Box Scores by Date by Competition (single competition)
  2. Projected Player Game Stats by Week/Date (w/ Lineups, Injuries, FanDuel/DraftKings Salaries)
    The projected player game stats APIs are one of the most powerful piece that we provide. They are perfectly tailored toward building daily fantasy sports lineup optimizers and other tools. We recommend syncing the Projected Player Game Stats by Week/Date as often as every ten minutes, or as little as every 4 hours, depending on the time of day, and whether games are starting within the next few hours or not. For instance, if a game for the given league is scheduled to start within the next 4-6 hours, you should sync this data every ten minutes. However, if it's going to be 6+ hours until a game starts, then it makes more sense to sync this data every 1-4 hours, depending on your application. In this feed, projected stats, injuries, and starting lineup information are all updated every ten minutes in the 4-6 hours leading up to game time. Here are the links to the Projected Player Game Stats by Week/Date per league:
    API Docs
    NFL Projected Player Game Stats by Week
    NFL Projected Fantasy Defense Game Stats by Week (NFL ONLY)
    MLB Projected Player Game Stats by Date
    NBA Projected Player Game Stats by Date
    NHL Projected Player Game Stats by Date
  3. MLB Starting Lineups (MLB ONLY)
    In the MLB Projected Player Game Stats by Date feed, we also provide starting lineups (projected and confirmed). By noon ET every morning, every team playing has a projected starting lineup (BattingOrder). Then, about 3-4 hours before game time, you'll see these projected starting lineups become official, as indicated by the BattingOrderConfirmed field. We recommend using this feed to ensure you have the most accurate and fastest MLB starting lineups in the industry.

Real Time Integration

Now that you have basic and more advanced post-game and pre-game data, you may wish to take it to the next level with a real-time integration, to allow live scores and play-by-play updates.

There are various challenges when implementing a real time scoring platform. But, if you have a plan formulated, it can go quite smoothly. We highly recommend considering the recommended approach to implementing real time scoring in your application. Even if you decide to go a different route, this guide may still provide some valuable insight and perspective.

Real Time Integration Workflow

This assumes you've completed the steps above, and the fixtures are synced to your database. If you haven't completed the integration steps above, you should do that before proceeding.

We recommend the following workflow for real time scoring. You'll create a scheduled task that runs on your server every minute. If you're a more advanced developer, you can implement a service that runs in the background (e.g. Windows Service).

  1. Check for Pending Games
    Check your database for any games that are pending (ie. they fit the following criteria):
    1. The game should have started (Game.DateTime < Now)
    2. The game DOES NOT have one of these statuses: Final, Postponed, Canceled (Game.Status not in ('Final', 'Postponed', 'Canceled'))
  2. If any games are pending
    If there are any pending games, then continue, otherwise, quit.
  3. Box Scores
    If any games match the criteria, you'll want to pull the latest data for each game. You can do this one of two ways.
    1. Using distinct days from games that are pending, pull the latest box score data by date (API Call: Box Scores by Date)
    2. Loop the pending games and pull the latest box score data by GameID (API Call: Box Score)
  4. Delta Box Scores
    One more important note, instead of using the full box score data, you can use the delta box scores instead. This will allow you to get even faster real time integration, since you will only receive player stats that have changed in the last X minutes. (more information on the Box Scores by Date Delta APIs below)

Refreshing Completed Games

We recommend refreshing the latest box scores of all completed games (for today and yesterday), every 10 minutes to 2 hours (depending on your application). This should ensure any stat corrections come through and are propagated to your system in a timely manner. Completed games are defined as: Game.Status in ('Final', 'Postponed', 'Canceled').

Box Scores by Date Delta

We recommend using the Box Scores by Date Delta API for real time integration. This API delivers all the game details, as well as player/team stats, and any other data points that are updated live during games. This API works best for real time integration because it will only return player stats that have changed in the past X minutes (defined by your API call). If you're calling our API every 5 seconds (for instance), we'd recommend passing 1 in the minutes. However, if you're calling the API every 3 minutes, we recommend passing 4 or 5 in the minutes parameter, to ensure nothing is missed.

IMPORTANT NOTE: The API will always return the players' full stats for the game up until that point in time. For instance, if Aaron Rodgers has 72 yards passing, and then he completes an 18 yard pass, his stats will still show the full sum of 90 yards passing in the delta APIs. So, even though the API is labeled delta, it is actually representing "recently updated" information.

API Docs

NFL Box Scores Delta
MLB Box Scores Delta
NBA Box Scores Delta
NHL Box Scores Delta
CFB Box Scores Delta
CBB Box Scores Delta
Soccer Box Scores Delta (all competitions)
Soccer Box Scores Delta by Competition (single competition)

All Done

Now you know how to complete a basic, advanced, and real-time integration. If you are interested in betting odds and other gaming data, you may now wish to learn about ourAggregated Odds feeds.

Copyright © 2024 SportsDataIOTM