Sports Data API Implementation Guide

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

At FantasyData, 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!

Fixtures Integration

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.

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).

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

ScheduleSync 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).

StandingsSync standings every evening or once every hour if you prefer.

Rosters & Player DetailsSync 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: API DocsNFL Projected Player Game Stats by WeekNFL Projected Fantasy Defense Game Stats by Week(NFL ONLY)MLB Projected Player Game Stats by DateNBA Projected Player Game Stats by DateNHL 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.

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'))

If any games are pending
If there are any pending games, then continue, otherwise, quit.

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.

Using distinct days from games that are pending, pull the latest box score data by date (API Call: Box Scores by Date)

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.

All Done

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.

FantasyData.com is an unofficial and independent source of information not affiliated with the National Football League (NFL), the NFLPA or any other affiliates. For official statistics, please visit NFL.com.

Free Live Data Feeds

Scrambled Data

Scrambled data means the data values are adjusted up or down by about 20% from their actual value. Certain types of data are scrambled in our Free Trial and Developer Subscription, such as team & player stats and fantasy stats.
All other data, such as teams, players, schedules, etc, including their unique IDs,
are not scrambled and the same as you would see in our Post-Game, Live and Real-Time Subscriptions.

This is done so that you can use the Free Trial (1,000 API calls/mo) or
Developer Subscription (unlimited API calls, $29/mo) to complete the majority of your integration
before having to upgrade to one of our premium API subscriptions.

RESTful Web Service Model

Representational State Transfer (REST) is a style of web service architecture for developing scalable,
distributed systems.
REST has emerged as the preferred web service design model of technology organizations.