FAQs

What format are date fields presented in?

When we present date only values we present these in the ISO 8601 standard format.
ex: 2013-04-03
We use these for attributes that have date and no time (such as birthdate). For more information: https://en.wikipedia.org/wiki/ISO_8601

What format are the date/time fields presented in?

All of our Date/Time attributes are in UTC, presented in the ISO 8601 standard format.
ex: 2013-04-03T18:15:00+00:00
For more information: https://en.wikipedia.org/wiki/ISO_8601

How do I locate the TTL (Time to Live)/cache on an API endpoint?

The cache (in seconds) can be accessed in the returned header information on each RESTful API call, under cache-control.
ex. cache-control: max-age=1, public, s-maxage=1 or
cache-control: public, must-revalidate, max-age=120

Note that, for select game-centric endpoints, the TTL may adjust when an event is live. This information is available for each endpoint on our developer portal.

When are the game scores added to the Schedule feeds?

Game and period scores will be added to the feed when the game status changes to complete.

What are the season types and their descriptions?

Here are the valid season types and their descriptions:

• PRE – Pre-season
• REG – Regular season
• PST – Post-season

What are the player positions I can expect to see?

Below is a list of player positions that appear in our feeds and their descriptions. Note that additional decommissioned positions may appear in older seasons.

• C - Center
• CB - Cornerback
• DB - Defensive Back
• DE - Defensive End
• DL - Defensive Lineman
• DT - Defensive Tackle
• FB - Fullback
• FS - Free Safety
• G - Offensive Guard
• K - Kicker
• LB - Linebacker
• LS - Long Snapper
• MLB - Middle Linebacker
• NT - Nose Tackle
• OG - Offensive Guard
• OL - Offensive Lineman
• OLB - Outside Linebacker
• OT - Offensive Tackle
• P - Punter
• QB - Quarterback
• RB - Running Back
• SAF - Safety
• SS - Strong Safety
• T - Offensive Tackle
• TE - Tight End
• WR - Wide Receiver

How are player positions handled in the feeds?

Players may receive a “game” position, that position may not match the position listed on the player’s profile outside the game.

What are the player statuses and their descriptions?

Below is a list of the currently valid player statuses and their descriptions. Note that additional decommissioned statuses may appear in older seasons.

• ACT - Active
• DUP - Duplicate player profile. All profiles marked as duplicates can be ignored.
• EXE - Exempt
• FRES - Reserve/Future
• IR - Injured Reserve
• IRD - Injured Reserve - Designated for Return
• NON - Non-football related injured reserve
• NWT - Not with team
• PRA - Practice Squad
• PRA_IR - Practice Squad Injured Reserve
• PUP - Physically unable to perform
• RET - Retired
• SUS - Suspended
• UDF - Unsigned draft pick
• UFA - Unsigned free agent
  
  

What are the player game statuses and when can I expect them to populate?

Below is a list of currently valid player game statuses.

• deactivated
• dnp (Did Not Play)
• played
• started

These player game statuses will appear within the Game Roster feed exclusively. When a game is set to created all players are marked as played. At the conclusion of the game players are adjusted to deactivated,dnp, and played as necessary.

What are the venue roof types I can expect to see?

Here are the valid roof types: outdoor, dome, or retractable_dome

What are the venue surfaces I can expect to see?

Here are the valid venue surfaces: turf or artifical

What are the game statuses and their descriptions?

Here are the valid game statuses and their descriptions:

• scheduled – The game is scheduled to occur.
• created – Game data (rosters, officials, etc) are being pre-loaded in preparation for the game.
• inprogress – The game is in progress.
• halftime – The game is currently at halftime.
• complete – The game is over, but stat validation is not complete.
• closed – The game is over and the stats have been validated.
• cancelled – The game has been cancelled. No makeup game will be played as a result.
• postponed – The game has been postponed, to be made up at another day and time. Once the makeup game is announced, a new game and ID will be created and scheduled on the announced makeup date. You should request the scheduled feed(s) regularly to identify the re-scheduled makeup game(s).
• delayed – The scheduled game, or a game that was in progress, is now delayed for some reason.
• suspended – The game has been suspended and will be rescheduled in the future, continuing where they left off. The game ID will remain the same.
• flex-schedule – The game is currently scheduled to occur on a specific date and time, however, it will more than likely be moved to a different time for broadcast purposes.
• time-tbd – The game has been scheduled, but a time has yet to be announced.

What are the start and end reasons for a drive that I can expect to see in the feeds?

Here are the end reasons for a drive:

• UNKNOWN – Start/End
• Touchdown – Start/End
• Safety – End
• Field Goal – Start/End
• Missed FG – Start/End
• Blocked FG – Start/End
• Blocked FG, Downs – Start/End
• Blocked FG, Safety – End
• Punt – Start/End
• Blocked Punt – Start/End
• Blocked Punt, Downs – Start/End
• Blocked Punt, Safety – End
• Downs – Start/End
• Interception – Start/End
• Fumble – Start/End
• Fumble, Safety - End
• Missed FG – End
• Muffed FG – Start/End
• Muffed Punt – Start
• Muffed Kickoff – Start
• Kickoff – Start
• Own Kickoff – Start
• Onside Kick – Start
• Kickoff, No Play – Start
• End of Half – End
• End of Game – End

What are the event types I can expect to see in the feeds?

Here are the valid event types:

• setup
• timeout
• tv_timeout
• two_minute_warning
• comment
• period_end
• game_over

What are the play types I can expect to see in the feeds?

Here are the valid play types:

• pass
• rush
• faircatch_kick
• extra_point
• conversion
• free_kick
• kickoff
• punt
• field_goal
• penalty

What are the point after score types I can expect to see in the feeds?

Here are the valid score types:

• extra_point
• conversion
• penalty

What are the possible official assignments I can expect to see in the feeds?

Here are the valid official assignments:

• referee
• umpire
• headlinesman
• linejudge
• fieldjudge
• sidejudge
• backjudge
• downjudge
• replayofficial

How are assisted sacks calculated in the feeds?

Assisted sacks are credited when two player sack the quarterback. We provide this in the play-by-play feed and game boxscore as an integer. Those sacks are rolled up into the sacks stat and can be a float, so if a player had 3 ast_sacks and 2 sacks in a game his game-level sack number would be 3.5.

What are the possible injury status values I can expect to see in the feeds?

Here are the valid injury status values:

• Questionable - The player has a 50/50 chance to play
• Doubtful - The player is very unlikely to play
• Out - The player will not play
  
  

What are the possible detail categories I can expect to see in the feeds?

Here are the valid detail categories:

• aborted_snap
• aborted_snap_recovery
• blocked_kick
• blocked_kick_recovery
• defensive_conversion_fumble_recovery
• defensive_conversion_interception_recovery
• defensive_conversion_recovery
• downed
• extra_point_attempt
• fair_catch
• field_goal
• field_goal_return
• forced_fumble
• fumble
• fumble_out_of_bounds
• kick_off
• kick_off_return
• lateral
• muffed_kick
• onside_kick_off
• onside_kick_off_recovery
• opponent_fumble_recovery
• out_of_bounds
• own_fumble_recovery
• pass_completion
• pass_incompletion
• pass_interception
• pass_interception_return
• pass_reception
• penalty
• punt
• punt_return
• review
• rush
• sack
• safety
• tackle
• touchback
• touchdown
• two_point_attempt
• two_point_pass
• two_point_return
• two_point_rush

What are subjective stats and how are they handled?

Subjective stats are variety of data points that go beyond typical stats like yards, pass attempts, and touchdowns. Due to how the data is collected, it requires an operator to re-watch the game, thus there is a delay on when it is provided in the feeds. 

These data points are delivered the following Tuesday by the end of the day (6:00 pm ET) and will show up in the existing NFL API feeds. The data is available in both XML and JSON feed formats. As the demand rises for additional data points we will continue to refine the data set collected.

Which statistics are subjective?

Here are the valid subjective statistics:

• Batted Passes
• Broken Tackles
• Catchable Pass
• Defender Blitz
• Defensive Completion
• Defensive Target
• Dropped Pass
• Fake Field Goal
• Fake Punt
• Hang Time
• Hash Mark
• Huddle
• Hurry
• Incompletion Type
• Kneel down
• Knockdown
• Left Tightends
• Men in Box
• Missed Tackle
• On Target Throws
• Onside Attempt
• Onside Success
• Pass Route
• Play Action
• Play Direction
• Players Rushed
• Pocket Location
• Pocket Time
• QB at Snap
• QB Blitz
• QB Hurry
• QB Knockdown
• Right Tightends
• Run Pass Option
• Running Lane
• Scramble
• Screen Pass
• TE Location
• Team Blitz
• Yards After Contact

When can I expect NFL draftees to populate in the Prospects endpoint?

Prospects are typically added in mid to late March, after the draft order is determined by the NFL.

How is the data within the Draft feeds populated?

Sportradar’s experts seed players from our NCAA database. We use a variety of sources to generate a comprehensive list of players who expect to be drafted. The list is typically 500+ players.

How is an NFL prospect specified as a top prospect?

Top prospects are subjective. We use the same sources for top prospects as we do when creating the initial draft pool.

Do you cover the Pro Bowl?

No. We do not currently cover the Pro Bowl in the NFL API.