Live Match Updates

To avoid confusion and ensure you're accessing available data, refer to our Seasons feed. This resource lists all the seasons for which we have data.

For example: To ensure data availability for future seasons, such as a schedule in advance of when a season begins, first check the Seasons feed to verify that data for that specific season is already provided.

Starting with this feed can prevent unnecessary errors and streamline your data retrieval process.

Getting Started - Accessing the Games You Want

1. Find the game ID by querying one of the following feeds:

   • Current Season Schedule
   • Current Week Schedule
   • Season Schedule
   • Weekly Schedule
     
     

     👍

     Tip - Use Current Schedule Feeds

     You can use the Current Week Schedule or Current Season Schedule feeds, to verify the specific week or type of season that's currently in progress. These feeds automatically return the schedule for the ongoing season or week, which is useful if you're unsure about the current part of the season.

     Use these feeds for non-live schedule retrieval only.

2. Use the Game Id to access live data from any of the following feeds:

   Data Type	Recommended Feed
   Play-by-Play Data	- Game Play-by-Play - Push Events
   Scoring Updates	- Game Boxscore - Game Play-by-Play
   Game Statistics	- Game Statistics - Push Statistics

   
   

   📘

   Using Game IDs for Push Feeds

   Using a specific game ID is optional when filtering the push events or push statistics feeds. Without specifying a game ID, the feeds will automatically return data for all games currently in progress.

Utilizing Schedule Feeds

You only need to call the schedule feeds once or twice a day at most to get the most up-to-date season information. Follow these steps:

1. Load the necessary schedule using any of the schedule feeds.
2. To stay updated on any scheduling changes, refer to the Daily Change Log feed. More details are available in the Change Log section.
3. Ensure to start requests to live games no earlier than 10 minutes before the scheduled time.

Utilizing the Current_Week Path in API Requests:

The 'current_week' path convention in API requests simplifies retrieving data specific to the ongoing week of an NFL season.

Current Week Schedule:

[https://api.sportradar.com/nfl/official/{access_level}/v7/{language}/games/current_week/schedule.{format}]

By using this convention, you avoid the need to specify the season's year and type (such as regular season or playoffs) in your query parameters. This feature is particularly useful for applications that need to automatically fetch the most current game week information without manual updates to the query as the season progresses.

Limitations of Schedule Feeds for Real-Time Game Status Updates:

• The Season Schedule feed provides game status information, including statuses like "closed," “inprogress,” and "complete." However, it does not update as frequently as the real-time game feeds, which offer more current game status updates.
• For more immediate updates, consider using more real-time feeds like the Game Play-by-Play or Game Boxscore endpoints, which are designed to provide the most up-to-date status changes during games.

Play-by-Play Data

Play-by-Play data provides a detailed, sequential account of every action that occurs during a game, including all plays and events. This data type is crucial for analyzing game flow, player performance, and tactical decisions in real-time.

Option 1 - Using the Game Play-by-Play Feed

You can call the Game Play-by-Play feed to get a live play-by-play timeline, including possession and ball location as well as all team and player statistics earned on each play.

How to Pull the Game Play-by-Play Feed:

1. Ensure you have your game IDs and schedules.
2. Call the Game Play-by-Play feed: Use your game ID to request the Play-by-Play feed for real-time updates throughout the live game.

Recommended Pull Frequency:

• Request this feed no sooner than 10 minutes before the scheduled start of the game (status = scheduled) based on your specific needs.
• Once the game is in progress (status = inprogress), you may query the feed as necessary.
• The endpoint offers real-time data updates and maintains a two-second TTL once the game status changes to inprogress.
• Utilize the Daily Change Log to capture data changes after a game has ended.

Play-by-Play Example:

     
      "pbp": [
        {
          "type": "drive",
          "id": "c7a8bcfd-2f3d-435e-9871-a6df0211c7e0",
          "sequence": 1,
          "start_reason": "Kickoff",
          "end_reason": "Punt",
          "play_count": 3,
          "duration": "1:25",
          "first_downs": 0,
          "gain": 0,
          "penalty_yards": 0,
          "created_at": "2023-09-10T17:03:30+00:00",
          "updated_at": "2023-09-10T17:06:09+00:00",
          "team_sequence": 1,
          "start_clock": "15:00",
          "end_clock": "13:35",
          "first_drive_yardline": 75,
          "last_drive_yardline": 75,
          "farthest_drive_yardline": 73,
          "net_yards": 0,
          "pat_points_attempted": 0,
          "offensive_team": {
            "points": 0,
            "id": "82cf9565-6eb9-4f01-bdbd-5aa0d472fcd9"
          },
          "defensive_team": {
            "points": 0,
            "id": "f7ddd7fa-0bae-4f90-bc8e-669e4d6cf2de"
          },
          "events": [
            {
              "type": "play",
              "id": "5ccbfc20-4ff8-11ee-80fc-dbdc3b30b913",
              "sequence": 1694365410350,
              "clock": "15:00",
              "home_points": 0,
              "away_points": 0,
              "play_type": "kickoff",
              "wall_clock": "2023-09-10T17:03:23+00:00",
              "description": "B.McManus kicks 65 yards from JAC 35 to the IND End Zone. Touchback.",
              "fake_punt": false,
              "fake_field_goal": false,
              "screen_pass": false,
              "hash_mark": "Left Hash",
              "play_action": false,
              "run_pass_option": false,
              "created_at": "2023-09-10T17:03:30+00:00",
              "updated_at": "2023-09-11T16:31:47+00:00",
              "start_situation": {
                "clock": "15:00",
                "down": 0,
                "yfd": 0,
                "possession": {
                  "id": "f7ddd7fa-0bae-4f90-bc8e-669e4d6cf2de",
                  "name": "Jaguars",
                  "market": "Jacksonville",
                  "alias": "JAC",
                  "sr_id": "sr:competitor:4386"
                },
                "location": {
                  "id": "f7ddd7fa-0bae-4f90-bc8e-669e4d6cf2de",
                  "name": "Jaguars",
                  "market": "Jacksonville",
                  "alias": "JAC",
                  "sr_id": "sr:competitor:4386",
                  "yardline": 35
                }
              },
              "end_situation": {
                "clock": "15:00",
                "down": 1,
                "yfd": 10,
                "possession": {
                  "id": "82cf9565-6eb9-4f01-bdbd-5aa0d472fcd9",
                  "name": "Colts",
                  "market": "Indianapolis",
                  "alias": "IND",
                  "sr_id": "sr:competitor:4421"
                },
                "location": {
                  "id": "82cf9565-6eb9-4f01-bdbd-5aa0d472fcd9",
                  "name": "Colts",
                  "market": "Indianapolis",
                  "alias": "IND",
                  "sr_id": "sr:competitor:4421",
                  "yardline": 25
                }
              },
              "statistics": [
                {
                  "stat_type": "kick",
                  "attempt": 1,
                  "yards": 65,
                  "net_yards": 40,
                  "touchback": 1,
                  "onside_attempt": 0,
                  "onside_success": 0,
                  "squib_kick": 0,
                  "player": {
                    "id": "6444feb1-f5a4-4b45-9a45-79308a4445fd",
                    "name": "Brandon McManus",
                    "jersey": "10",
                    "position": "K",
                    "sr_id": "sr:player:830901"
                  },
                  "team": {
                    "id": "f7ddd7fa-0bae-4f90-bc8e-669e4d6cf2de",
                    "name": "Jaguars",
                    "market": "Jacksonville",
                    "alias": "JAC",
                    "sr_id": "sr:competitor:4386"
                  }
                },
                {
                  "stat_type": "return",
                  "touchback": 1,
                  "category": "kick_return",
                  "team": {
                    "id": "82cf9565-6eb9-4f01-bdbd-5aa0d472fcd9",
                    "name": "Colts",
                    "market": "Indianapolis",
                    "alias": "IND",
                    "sr_id": "sr:competitor:4421"
                  }
                }
              ],
              "details": [
                {
                  "category": "kick_off",
                  "description": "B.McManus kicks 65 yards from JAC 35 to the IND End Zone.",
                  "sequence": 0,
                  "yards": 65,
                  "result": "touchback",
                  "start_location": {
                    "alias": "JAC",
                    "yardline": 35
                  },
                  "end_location": {
                    "alias": "IND",
                    "yardline": 0
                  },
                  "players": [
                    {
                      "id": "6444feb1-f5a4-4b45-9a45-79308a4445fd",
                      "name": "Brandon McManus",
                      "jersey": "10",
                      "position": "K",
                      "sr_id": "sr:player:830901",
                      "role": "kick"
                    }
                  ]
                },
                {
                  "category": "touchback",
                  "description": "Touchback.",
                  "sequence": 1,
                  "result": "touchback",
                  "start_location": {
                    "alias": "IND",
                    "yardline": 0
                  },
                  "end_location": {
                    "alias": "IND",
                    "yardline": 25
                  },
                  "players": [
                    {
                      "id": "6444feb1-f5a4-4b45-9a45-79308a4445fd",
                      "name": "Brandon McManus",
                      "jersey": "10",
                      "position": "K",
                      "sr_id": "sr:player:830901",
                      "role": "kick"
                    }
                  ]
                }
              ]
            },
            {

In this play-by-play example, a drive begins with a kickoff by the Jaguars' Brandon McManus from their 35-yard line, which results in a touchback as the ball reaches the end zone. The Colts then start their drive from their 25-yard line but fail to make any progress over three plays, gaining zero yards and ending the drive with a punt. This brief drive, lasting only 1 minute and 25 seconds, includes no penalties or first downs, demonstrating a quick defensive halt by the Jaguars. The sequence is part of the detailed play-by-play data that captures every play's dynamics, including starting and ending situations, which are crucial for in-depth game analysis and stats tracking.

You could visualize this play in your application by creating a graphic similar to the one shown, illustrating the kickoff by the Jaguars' Brandon McManus that results in a touchback, followed by the Colts' unsuccessful attempt to advance, culminating in a punt.

Use Case:

In your sports analytics application, you could track and display detailed play-by-play data like the kickoff by Brandon McManus of the Jacksonville Jaguars. For instance, you can analyze his kick that traveled 65 yards resulting in a touchback, and note the drive duration of 1:25 minutes. This information is crucial for understanding game dynamics and player performance, which could be vital for making informed decisions in fantasy sports leagues.

Option 2 - Using the Push Events and Play-by-Play Feeds

The Push Events feed delivers live play-by-play data with a single API call, optimizing real-time updates and reducing API calls. However, it may lack the detailed boxscore information and broader league statistics found in the Play-by-Play feed.

👍

Tip - Compare Data Points

Compare the data points returned by the Game Play-by-Play feed with those from the Push Events feed to understand the specific information each provides.

Streamline your access to live game updates by combining the Push Events and Game Play-by-Play feeds:

1. Open a connection with a single call to the Push Events feed to receive real-time updates.
2. Push feeds automatically deliver JSON payloads through a push service, minimizing the number of calls required.
3. Supplement this with the RESTful Game Play-by-Play feed to obtain detailed statistics and comprehensive game data when needed.

Note: You need to be a Realtime customer to make use of the Push feature.

How to Pull the Push Events Feed:

• Add the match parameter with the specific game id. Without the match parameter the feed will return data for all live NFL games.
• The Push Events Feed should not be used exclusively; supplement it with the Game Play-by-Play feed for comprehensive data coverage.
• Certain statistics are only available through the RESTful API and not included in the Push Events Feed.
• In the event of a disconnection from the Push Events Feed, it's not possible to resume where you left off. To ensure continuous coverage, use multiple Push Feeds and supplement with RESTful feeds as a fallback to retrieve any missed timeline information during live games.

👍

Tip - Open Simultaneous Push Connections

Opening multiple connections to the push events feed boosts your application's reliability and flexibility. It enables simultaneous monitoring of various games or data types and ensures continuous data flow, even if one connection fails. This method also enhances scalability and data management, vital for applications needing real-time updates.

Play-by-Play vs. Push Scenario:

In a live sports tracking app, you might use the Push Events feed to receive real-time notifications of major events like touchdowns and penalties. However, for a user-requested feature that provides a detailed timeline of each drive, including minor plays and player statistics, you may supplement with the Game Play-by-Play feed to fetch comprehensive game details not covered by the push notifications. This ensures the app delivers both quick updates and in-depth game analysis.

📸

Game Status Workflows

For more on what feeds look like throughout the duration of a game, see the Game Status Workflow page.

Scoring Updates

If your main interest is scoring data, use the Game Boxscore feed. While the Game Play-by-Play and Push Events feeds also include scoring data, the Game Boxscore feed offers more detailed scoring information for each team, complete with play-by-play breakdowns of all scoring drives in NFL games.

How to Pull the Game Boxscore Feed:

1. Ensure you have your game IDs and schedules.
2. Call the Game Boxscore feed: Use your game ID to request the Game Boxscore feed for real-time scoring updates throughout the live game.

Recommended Pull Frequency:

• Request this feed no sooner than 10 minutes before the scheduled start of the game (status = scheduled) based on your specific needs.
• Once the game is in progress (status = inprogress), you may query the feed as necessary.
• The endpoint offers real-time data updates and maintains a two-second TTL once the game status changes to inprogress.
• Utilize the Daily Change Log to capture data changes after a game has ended.

Game Boxscore Example:

        
          "type": "play",
          "id": "27479930-6384-11ed-8923-235f4c176b64",
          "sequence": 1668365517081,
          "clock": "11:42",
          "home_points": 17,
          "away_points": 7,
          "play_type": "pass",
          "wall_clock": "2022-11-13T18:51:47+00:00",
          "description": "K.Cousins pass short middle complete to BUF 39. Catch made by J.Jefferson at BUF 39. Gain of 14 yards. Tackled by D.Jackson at BUF 38.",
          "players_rushed": 5,
          "men_in_box": 6,
          "fake_punt": false,
          "fake_field_goal": false,
          "screen_pass": false,
          "blitz": true,
          "play_direction": "Right",
          "left_tightends": 0,
          "right_tightends": 0,
          "hash_mark": "Right Hash",
          "pocket_location": "Middle",
          "qb_at_snap": "Shotgun",
          "huddle": "Huddle",
          "pass_route": "Post",
          "play_action": false,
          "run_pass_option": false,
          "created_at": "2022-11-13T18:51:57+00:00",
          "updated_at": "2022-11-14T21:00:49+00:00",
          "start_situation": {
            "clock": "11:42",
            "down": 3,
            "yfd": 7,
            "possession": {
              "id": "33405046-04ee-4058-a950-d606f8c30852",
              "name": "Vikings",
              "market": "Minnesota",
              "alias": "MIN",
              "sr_id": "sr:competitor:4423"
            },
            "location": {
              "id": "33405046-04ee-4058-a950-d606f8c30852",
              "name": "Vikings",
              "market": "Minnesota",
              "alias": "MIN",
              "sr_id": "sr:competitor:4423",
              "yardline": 48
            }
          },
          "end_situation": {
            "clock": "11:03",
            "down": 1,
            "yfd": 10,
            "possession": {
              "id": "33405046-04ee-4058-a950-d606f8c30852",
              "name": "Vikings",
              "market": "Minnesota",
              "alias": "MIN",
              "sr_id": "sr:competitor:4423"
            },
            "location": {
              "id": "768c92aa-75ff-4a43-bcc0-f2798c2e1724",
              "name": "Bills",
              "market": "Buffalo",
              "alias": "BUF",
              "sr_id": "sr:competitor:4376",
              "yardline": 38
            }
          }

The example from the Gamebox Score feed illustrates its focus on detailed scoring plays, such as the play-by-play data for specific scoring drives. This play, a pass from Kirk Cousins to Justin Jefferson that resulted in a 14-yard gain, is a prime example. The detail provided includes game context like the clock time, points scored by both home and away teams, and a vivid description of the action on the field. Importantly, the end_situation node highlights the new set of downs and field position post-play, crucial for understanding the ongoing strategic decisions in the game.

The visual shows a summary from the Gamebox Score feed for a game between the Minnesota Vikings and the Buffalo Bills, detailing key game statistics like attendance, team scores, and individual performance highlights, like passing yards by Kirk Cousins and Josh Allen.

📘

Accessing Headshots and Team Logos

To access team logos and player headshots, use the Images API.

Use Case:

A sports analyst uses this data to enhance a broadcast or article, providing viewers or readers with a detailed breakdown of key plays that influenced the game's outcome. They can discuss the effectiveness of plays under pressure, the decision-making of the quarterback, and defensive responses, enriching the narrative of the game's pivotal moments. This insight helps in crafting more engaging and informed sports content.

Game Statistics

Game statistics encompass quantifiable data points collected from a sports event, detailing metrics such as scores, player performance stats (like yards gained, tackles, assists), and team comparisons. These statistics are essential for evaluating overall team effectiveness, player contributions, and strategic outcomes.

Option 1 - Using the Game Statistics Feed

The Game Statistics feed provides comprehensive game-level statistics, including detailed team and player performance metrics for each team in an NFL game.

How to Pull the Game Statistics Feed:

• Request this feed no sooner than 10 minutes before the scheduled start of the game (status = scheduled) based on your specific needs.
• Once the game is in progress (status = inprogress), you may query the feed as necessary.
• The endpoint offers real-time data updates and maintains a two-second TTL once the game status changes to inprogress.
• Utilize the Daily Change Log to capture data changes after a game has ended.

Game Statistics Example:

"statistics": {
  "home": {
    "id": "768c92aa-75ff-4a43-bcc0-f2798c2e1724",
    "name": "Bills",
    "market": "Buffalo",
    "alias": "BUF",
    "sr_id": "sr:competitor:4376",
    "summary": {
      "possession_time": "33:46",
      "avg_gain": 6.8,
      "safeties": 0,
      "turnovers": 4,
      "play_count": 72,
      "rush_plays": 27,
      "total_yards": 486,
      "fumbles": 2,
      "lost_fumbles": 2,
      "penalties": 7,
      "penalty_yards": 64,
      "return_yards": 71
    },
    "rushing": {
      "totals": {
        "avg_yards": 6.481,
        "attempts": 27,
        "touchdowns": 2,
        "tlost": 4,
        "tlost_yards": -4,
        "yards": 175,
        "longest": 25,
        "longest_touchdown": 5,
        "redzone_attempts": 7,
        "first_downs": 9,
        "broken_tackles": 1,
        "kneel_downs": 0,
        "scrambles": 5,
        "yards_after_contact": 60
      },
      "players": [
        {
          "id": "6130be96-edf3-4361-b666-860c4ec46e7d",
          "name": "Isaiah McKenzie",
          "jersey": "06",
          "position": "WR",
          "sr_id": "sr:player:1130247",
          "first_downs": 1,
          "avg_yards": 18,
          "attempts": 1,
          "touchdowns": 0,
          "yards": 18,
          "longest": 18,
          "redzone_attempts": 0,
          "tlost": 0,
          "tlost_yards": 0,
          "broken_tackles": 0,
          "kneel_downs": 0,
          "scrambles": 0,
          "yards_after_contact": 0
        },
        {
          "id": "31c376b7-2e10-473a-aa54-d9f709a5b93e",
          "name": "Duke Johnson",
          "jersey": "22",
          "position": "RB",
          "sr_id": "sr:player:834683",
          "first_downs": 1,
          "avg_yards": 2,
          "attempts": 2,
          "touchdowns": 0,
          "yards": 4,
          "longest": 4,
          "redzone_attempts": 1,
          "tlost": 0,
          "tlost_yards": 0,
          "broken_tackles": 0,
          "kneel_downs": 0,
          "scrambles": 0,
          "yards_after_contact": 3
        },
        {
          "id": "a961b0d4-5d7c-438e-90f0-2e1fa09f6c89",
          "name": "Devin Singletary",
          "jersey": "26",
          "position": "RB",
          "sr_id": "sr:player:1202676",
          "first_downs": 3,
          "avg_yards": 3.615,
          "attempts": 13,
          "touchdowns": 2,
          "yards": 47,
          "longest": 21,
          "longest_touchdown": 5,
          "redzone_attempts": 4,
          "tlost": 3,
          "tlost_yards": -3,
          "broken_tackles": 1,
          "kneel_downs": 0,
          "scrambles": 0,
          "yards_after_contact": 21
        },
        {
          "id": "ce5de0e5-9f76-42ee-b93a-3ef88af9b0a7",
          "name": "James Cook",
          "jersey": "28",
          "position": "RB",
          "sr_id": "sr:player:1415199",
          "first_downs": 0,
          "avg_yards": 4.4,
          "attempts": 5,
          "touchdowns": 0,
          "yards": 22,
          "longest": 8,
          "redzone_attempts": 2,
          "tlost": 1,
          "tlost_yards": -1,
          "broken_tackles": 0,
          "kneel_downs": 0,
          "scrambles": 0,
          "yards_after_contact": 14
        },
        {
          "id": "3069db07-aa43-4503-ab11-2ae5c0002721",
          "name": "Josh Allen",
          "jersey": "17",
          "position": "QB",
          "sr_id": "sr:player:1208608",
          "first_downs": 4,
          "avg_yards": 14,
          "attempts": 6,
          "touchdowns": 0,
          "yards": 84,
          "longest": 25,
          "redzone_attempts": 0,
          "tlost": 0,
          "tlost_yards": 0,
          "broken_tackles": 0,
          "kneel_downs": 0,
          "scrambles": 5,
          "yards_after_contact": 22
        }
      ]
    },
    "receiving": {
      "totals": {
        "targets": 41,
        "receptions": 29,
        "avg_yards": 11.379,
        "yards": 330,
        "touchdowns": 1,
        "yards_after_catch": 109,
        "longest": 25,
        "longest_touchdown": 11,
        "redzone_targets": 7,
        "air_yards": 221,
        "first_downs": 17,
        "broken_tackles": 1,
        "dropped_passes": 1,
        "catchable_passes": 1,
        "yards_after_contact": 36
      },
    },
  },
},

In the example of the Buffalo Bills, the statistics include time of possession, average gains, turnovers, and detailed rushing metrics such as attempts, average yards per attempt, touchdowns, and total yards gained. These statistics help in understanding the effectiveness of the team's offensive strategies and player performances during the game.

You can visually represent key game statistics in your applications, showcasing essential data such as passing and rushing yards, turnovers, and time of possession. This format aids in quickly conveying the effectiveness of team strategies and player performances to your users.

Use Case

Coaches and sports analysts can use these statistics to evaluate player performance and team efficiency during specific game situations. This data helps in making informed decisions on player rotations and game strategies, particularly by analyzing areas like rushing effectiveness, turnover margins, and penalty impacts on game outcomes. This is crucial for adjusting training focuses and preparing for upcoming opponents, ensuring a tactical advantage in future matchups.

Option 2 - Using the Push Statistics Feed

The Push Statistics feed offers the same live stat data as the Game Statistics feed, with its main advantage being continuous real-time updates through a single API call, thereby reducing the total number of API calls required.

Streamline your access to live game updates by combining the Push Statistics feed:

1. Open a connection with a single call to the Push Statistics feed to receive real-time updates.
2. Push feeds automatically deliver JSON payloads through a push service, minimizing the number of calls required.

Note: To utilize the Push feature, you must be a Realtime customer. Additionally, using the Game Statistics feed as a backup is recommended for uninterrupted coverage.

How to Pull the Push Statistics Feed:

• Add the match parameter with the specific game id. Without the match parameter the feed will return data for all live NFL games.
• In the event of a disconnection from the Push Events Feed, it's not possible to resume where you left off.
  • To ensure continuous coverage, use multiple Push Feeds and supplement with RESTful feeds like Game Statistics as a fallback to retrieve any missed timeline information during live games.

Supplementing Stats Feeds with the Game Play-by-Play Feed

If you choose to use the Game Statistics or Push Statistics feeds and need detailed play-related statistics such as attempted field goals, out of bounds fumbles, and passes inside the 20-yard line, consider supplementing with the Game Play-by-Play feed. This integration will enrich your solution with comprehensive game data.

👍

Tip - Compare Data Points

Compare the data points returned by the Game Play-by-Play feed with those from the Game Statistics or Push Statistics feed to understand the specific information each provides.

Daily Change Log

The Daily Change Log endpoint allows for efficient tracking of daily changes to the NFL API without depleting your API call limits. It updates you on significant changes like schedule adjustments, game results, player updates (such as name or number changes), and team modifications.

The table below outlines scenarios and use cases for utilizing the Daily Change Log for applications that offer live game updates.

For optimal results, set a regular schedule to pull every 10 minutes or less (depending on your use case) to access the feed.