STATS Developer Center Developer Blog

RSS Feed

API Tips

In additional to the documentation portal, we have created a list of suggested URIs, containing helpful hints for efficient API usage.  Below is a list of a few suggestions.

(Please note that all sample calls listed below intentionally do not include the API key and signature within the query string.)

  • Calling for player year-to-date stats – Please avoid calling for stats of players who have not accumulated statistics for the season in question. 
    • The easiest way to avoid this string of unsuccessful calls is to first call for player stats by team:
      (api.stats.com/v1/stats/soccer/chlg/stats/players/?teamId=7149&season=2014)
      • Please make sure to always include “&teamId” for these current, year-to-date player stats calls.
    • If you are looking for additional stats above and beyond player YTD calls (e.g. player encyclopedia or individual player splits), use the above technique to first get and your set of playerId’s who have accrued YTD data, and then call those players one by one for encyclopedia or splits data.

 

  • Checking for games that have been updated – Rather than make calls to every game in case of changes, there’s an API call to check for any games updated today, by a specific date, or by a specific date and time (all times in GMT):
    • Games that have been updated (confirmed data last updated) today:
      (api.stats.com/v1/stats/basketball/nba/eventDataConfirmed/)
      By specific eventId:
      (api.stats.com/v1/stats/soccer/natl/eventDataConfirmed/1263097/)
    • Games that have been updated (confirmed data last updated) since the start of a specific date (May 2, 2014, as an example):(api.stats.com/v1/stats/basketball/nba/eventDataConfirmed/?confirmedSince=2014-05-02)
      By specific eventId:
      (api.stats.com/v1/stats/soccer/natl/eventDataConfirmed/1263097?confirmedSince=2014-06-16)
    • Games that have been updated (confirmed data last updated) since a specific date and time (21:00 on May 2, 2014, as an example):(api.stats.com/v1/stats/basketball/nba/eventDataConfirmed/?confirmedSince=2014-05-02T21:00:00)
      By specific eventId:
      (api.stats.com/v1/stats/soccer/natl/eventDataConfirmed/1263097?confirmedSince=2014-06-11T21:00:00)
  • What time did year-to-date and game logs data most recently update – this form of data updates overnight each night while a season is in progress.  The date/time (all time in GMT) return is by eventTypeId (if eventTypeId isn’t found, then it hasn’t been updated in the last 3 days): (api.stats.com/v1/stats/baseball/mlb/dateDataUpdated/)
    • TIP: The overnight processing usually occurs after midnight of the regional location where the sport takes place. For example, for United States sports, the overnight processing finishes about 2 to 3 hours after midnight of the United States Central time zone. The sport day must be finished. Sometimes sporting events take longer to complete and may extend the game day, such as sporting events in Hawaii, which is several time zones away from the other time zones in the United States.

  • Generating an API signature –Your unique API key and secret along with the current timestamp are used to create a SHA-256 hash string signature.
  • A few notes about this:
    • Storing your API key and secrete inside your JavaScript code files might not be the best solution since the files are not encrypted and are easily read through a browser.
    • Additionally, we recommend clients build a middle layer of protection between your users and our calls (for more on caching, see “Access and Data Storage” tips on the “Documentation” link).
    • This signature will remain active for a finite period of time, approximately five minutes.  As such, and in order to secure a successful return on your API call, it’s best not rely on utilizing a generated signature multiple times.

 

QUERY STRING PARAMETERS – the following parameters can be included in a query string to further filter information or flesh out more granular information. 

  • Available for FOOTBALL ONLY
    • &pbpDetails=true/false (defaults to false) – including “&pbpDetails” will output each individual part of a play when multiple sequences occur within the same play (such as a sack + fumble + fumble recovery + return).  The “lastPlayDetails” and “pbpDetails” are identical to “lastPlay” and “pbp,” respectively.(api.stats.com/v1/stats/football/nfl/events/1421247/?pbp=true&pbpDetails=true)
  • NFL ONLY: As shown in the data dictionary, NFL inactives are available (approximately) at least 30 minutes before the start of each game when “box=true” is included in the query string.
  • NBA/CBK Optical Events Only: To view player and ball coordinate location data (X,Y,Z) based on PBP sequence time, please pass the following parameters:
    • Sequence=true
    • startTimestamp=
      • Passing possessions=true, will return the start and end timestamp for each eventID.
    • durationSeconds=

Note: durationSeconds is limited to maximum value of 30 seconds.

 

------------------------------------------------------------------------------------------------

  • Player stats for players who played on multiple teams – the following three query string parameters can be grouped together, or separately, to return variations of a player’s stats, including when a player accumulated stats for more than one team in a current season.  Each parameter can be used together or individually, as well as included with a “playerId,” as shown in the examples below.
  • &teamId={teamId}
  • &isCurrentRoster=true/false (defaults to false)
    • This parameter is only applicable for current season calls.  If true, it returns ONLY the players currently on the team (this included players on IR/DL).  If false, the call returns anyone who has earned stats for that team that year, no matter their current status (or current team)
    • This parameter can be excluded when including a specific playerId in the query string
  • &statsFrom=('ALL','FULL','TEAM'; default to 'FULL')
    • Including this parameter will determine what to return for players who accumulated stats for multiple teams in one season.  For example, David Price (MLB) played for the Tampa Bay Rays and Detroit Tigers in 2014.
    • If a player changes teams and “&statsFrom=FULL” is included, the “teamId” should not be included since the player played for more than one team.
    • If “&statsFrom=TEAM” is included, then only that “teamId” should be included.
  • EXAMPLES – the below example is for David Price (playerId=388363), who began the 2014 MLB season with the Rays (teamId=254) and finished the season with the Tigers (teamId=230).  These calls will also work for the entire team if a specific playerId is not included in the query string.
  • &teamId=Tigers, &isCurrentRoster=true, &statsFrom=ALL: returns 3 records for Price: his total season 34 games, Rays 23 games, and Tigers 11 games
    (api.stats.com/v1/stats/baseball/mlb/stats/players/388363?isCurrentRoster=True&statsFrom=ALL)
  • &teamId=Tigers, &isCurrentRoster=true, &statsFrom=FULL: returns 1 record for Price: his total season 34 games
    (api.stats.com/v1/stats/baseball/mlb/stats/players/388363?teamId=230&isCurrentRoster=true&statsFrom=FULL)
  • &teamId=Tigers, &isCurrentRoster=false, &statsFrom=FULL: returns 1 record for Price: his total season 34 games
    (api.stats.com/v1/stats/baseball/mlb/stats/players/388363?teamId=230&isCurrentRoster=false&statsFrom=FULL)
  • &teamId=Tigers, &isCurrentRoster=true, &statsFrom=TEAM: returns 1 record for Price: his Tigers 11 games
    (api.stats.com/v1/stats/baseball/mlb/stats/players/388363?teamId=230&isCurrentRoster=true&statsFrom=TEAM)
  • &teamId=Rays, &isCurrentRoster=false, &statsFrom=TEAM: returns 1 record for Price: his Rays 23 games
    (api.stats.com/v1/stats/baseball/mlb/stats/players/388363?teamId=254&isCurrentRoster=true&statsFrom=TEAM)

 

Other Tips

Please review the returns of your API calls. If an API call returns with something other than “200” (Successful), then there are a few different possible problems.  Below are a few examples:

  • “404 Data Not Found” – the data you’re looking for is not available.
    • Example: Calling a day’s events when there are no games scheduled
    • It’s not in itself problematic to make a call with a “404” return, but continued calls with 404 returns count against the user’s allotment of API calls.
    • “403 Developer Over QPS” – each API account has a calls/second throttle limit.  Exceeding this limit will cause the API call to return unsuccessfully.  The calls will again return successfully once called again the next second.
      • The easiest way to avoid this problem is to design your calls to run after the preceding call has completed.
    • “403” Developer Over Limit” – similar to above, each API account has a daily/monthly threshold.  Unlike the “403 Developer Over QPS” return, the calls will continue unsuccessful returns until the new daily/monthly count is increased.  Please contact your STATS Project Manager regarding this problem.
  • Schedules are relatively static information, and can be called only a few times a day. 
    • In a playoff series, schedule records will occasionally update after games go final:
      • Filling in start times for games that previously were TBA
      • Filling in game records as teams advance
      • Removing previously existing “eventId”s for games that no longer will be played if a team advanced in a series
        • It’s important to check for each “eventId” during the playoffs and understand that it’s possible for “eventId”s to be removed, at which point those “eventId”s should not be called.  With a few proactive measures to take these points into account, you should be able to avoid repeated calls for missing games.
  • When making regular schedule calls:
    • Please be sure to appropriately filter the schedule to most accurately return the data desired.
      • Ordinarily, this refers to using the “eventTypeId” parameter.  Other examples are pertinent, depending on the league.  For example, with college sports:
        • The “top25PollId” parameter condenses the schedule to only the top 25 teams according to a specific poll.
        • The “conferenceId” parameter filters the schedule to a specific conference.
        • The “collegeSubDivisionId” parameter (CFB only) can limit your schedule to only FBS or FCS calls, if necessary.
      • Using these parameters not only will give you more specific data, but also will return it quicker since less data is involved.
    • Once a specific “eventId” is included in the query string, it renders other parameters moot (such as “date” or “eventTypeId”).
  • Boxscore information does not need to be called repeatedly once a game is final (“eventStatusId”=4).  Check the “isDataConfirmed” subnode to confirm when the boxscore is officially final (for example, “Score”=true indicates the game is officially over and “Box”=true indicates the official boxscore is available). 
    • Use the aforementioned “eventDataConfirmed” check for games that have been updated to see if there have been any post-game changes.
  • Similar to the above point, games do not need to be repeatedly called before they begin.  If the “eventStatus” remains in pre-game, then lineups should be the only thing that changes.
    • Lineups can be checked starting about 60 minutes before the start of the game.
    • Also within the “eventStatus” node, “isActive” is equal to false before a game starts and after it is over, as well as between quarters/periods/halves/innings.  Otherwise, “isActive” will update to true while a game is in progress.

 

As always, please contact your STATS project manager with any questions related to API usage.


[ Page 1 of 1 ]