Sports Data API Implementation Guide
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!
The first step toward integrating with our feeds is to sync the the fixtures to your database. Fixtures include timeframes, venues/stadiums, teams, and rosters/squads. This data does not change very often, so you can refresh it every evening during off-hours.
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).
- 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).
- 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.
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
Sync the team data every evening to ensure you have the latest team information.
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).
Sync standings every evening or once every hour if you prefer.
Rosters & Player Details
Sync the rosters & player details once every 2-4 hours to ensure you have the latest player movement, change in depth chart, injury status, and active status (Active, Suspended, Injured Reserve, etc). Please note that there are several ways to sync the latest player details in our various APIs. However, we recommend calling Player Details by Active and Player Details by Free Agent. Both APIs return the same XML/JSON structure, so you can use the same source code to sync both of these payloads. The roster & player detail feeds include player card info and injury status.
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:
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
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.
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:
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)
Real Time Integration
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).
Check for Pending Games
Check your database for any games that are pending (ie. they fit the following criteria):
- The game should have started
(Game.DateTime < Now)
- The game DOES NOT have one of these statuses: Final, Postponed, Canceled
(Game.Status not in ('Final', 'Postponed', 'Canceled'))
- The game should have started
If any games are pending
If there are any pending games, then continue, otherwise, quit.
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.
- Using distinct days from games that are pending, pull the latest box score data by date (API Call: Box Scores by Date)
- Loop the pending games and pull the latest box score data by GameID (API Call: Box Score)
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.
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)
Congratulations! You built an application that automatically loads real time NFL scores & stats only when necessary. Allow the process to continue indefinitely and it will only pull player stats when there is relevant data available.