Integration GuidesReference Docs
Coverage MatrixDocumentationChange LogLog InContact Us
Integration Guides
Coverage MatrixDocumentationChange LogLog InContact Us

Live Game Updates

Use this guide to effectively access live NBA game updates and statistics. It also covers the Daily Change Log endpoint which can be used to track postgame stat revisions.

Prerequisite - Accessing Available Seasons

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.

📆

Starting Year for Each Season

It's important to note that the season parameter uses the starting year of the season; for example, to retrieve data for the 2024-25 NBA season, you would use 2024 as the value for the season parameter.


Getting Started - Accessing the Games You Want

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

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

    Data TypeRecommended Feed
    Play-by-Play Data- Play-by-Play
    - Push Events
    Scoring Updates- Game Boxscore
    - Play-by-Play
    - Push Clock
    Game Statistics- Game Summary
    - 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.

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

  • The 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 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 Play-by-Play Feed

You can call the Play-by-Play feed to get a live play-by-play timeline, including shot types and locations, and on-court participants.

How to Pull the Play-by-Play Feed:

  1. Ensure you have your game IDs and schedules.
  2. Call the 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.
🏀
Accessing NBA Play-by-Play Data
Open Recipe

Play-by-Play Example:

{
  "id": "51da4cfc-64d2-4f21-b014-e5f617652f19",
  "clock": "11:08",
  "updated": "2024-04-02T01:37:26Z",
  "description": "GG Jackson misses three point jump shot",
  "wall_clock": "2024-04-01T23:12:10Z",
  "sequence": 1712013130200,
  "home_points": 0,
  "away_points": 0,
  "clock_decimal": "11:08",
  "number": 12,
  "event_type": "threepointmiss",
  "qualifiers": [
    {
      "qualifier": "fromturnover"
    }
  ],
  "attribution": {
    "name": "Grizzlies",
    "market": "Memphis",
    "id": "583eca88-fb46-11e1-82cb-f4ce4684ea4c",
    "team_basket": "left",
    "sr_id": "sr:team:3415",
    "reference": "1610612763"
  },
  "location": {
    "coord_x": 297,
    "coord_y": 516,
    "action_area": "outsideleft"
  },
  "on_court": {
    "home": {
      "name": "Pistons",
      "market": "Detroit",
      "id": "583ec928-fb46-11e1-82cb-f4ce4684ea4c",
      "sr_id": "sr:team:3424",
      "reference": "1610612765",
      "players": [
        {
          "full_name": "Troy Brown Jr.",
          "jersey_number": "7",
          "id": "5350a897-aa31-4510-8feb-e709e1feb844",
          "sr_id": "sr:player:1320578",
          "reference": "1628972"
        },
        {
          "full_name": "Jaden Ivey",
          "jersey_number": "23",
          "id": "ec887131-efba-43a0-ad0a-0757ab3f0399",
          "sr_id": "sr:player:2077169",
          "reference": "1631093"
        },
        {
          "full_name": "Jalen Duren",
          "jersey_number": "0",
          "id": "00fb2704-aa25-4ef7-8972-cde454810810",
          "sr_id": "sr:player:2218398",
          "reference": "1631105"
        },
        {
          "full_name": "Tosan Evbuomwan",
          "jersey_number": "18",
          "id": "68ed2fac-e117-48e1-ac43-314098f600ea",
          "sr_id": "sr:player:1956598",
          "reference": "1641787"
        },
        {
          "full_name": "Cade Cunningham",
          "jersey_number": "2",
          "id": "57d55cd4-6ab8-4255-a248-bef800c0cbab",
          "sr_id": "sr:player:2068637",
          "reference": "1630595"
        }
      ]
    },
    "away": {
      "name": "Grizzlies",
      "market": "Memphis",
      "id": "583eca88-fb46-11e1-82cb-f4ce4684ea4c",
      "sr_id": "sr:team:3415",
      "reference": "1610612763",
      "players": [
        {
          "full_name": "Scotty Pippen Jr.",
          "jersey_number": "1",
          "id": "df62b7c5-faaa-4f37-a716-b7e034aa03eb",
          "sr_id": "sr:player:1831704",
          "reference": "1630590"
        },
        {
          "full_name": "Luke Kennard",
          "jersey_number": "10",
          "id": "a537047d-c29f-4dfe-99b0-3bac4e258dc7",
          "sr_id": "sr:player:1126375",
          "reference": "1628379"
        },
        {
          "full_name": "Santi Aldama",
          "jersey_number": "7",
          "id": "266cd359-f378-45c6-957e-6e21378e5219",
          "sr_id": "sr:player:1876228",
          "reference": "1630583"
        },
        {
          "full_name": "GG Jackson",
          "jersey_number": "45",
          "id": "28549c0f-c6e6-4757-a515-dbc2e1b78007",
          "sr_id": "sr:player:2438851",
          "reference": "1641713"
        },
        {
          "full_name": "Jaren Jackson Jr.",
          "jersey_number": "13",
          "id": "3e492a6a-ed3c-499d-b3f5-ff68ca16f6fd",
          "sr_id": "sr:player:1316824",
          "reference": "1628991"
        }
      ]
    }
  },
  "statistics": [
    {
      "type": "fieldgoal",
      "made": false,
      "shot_type": "jump shot",
      "three_point_shot": true,
      "shot_distance": 26.54,
      "team": {
        "name": "Grizzlies",
        "market": "Memphis",
        "id": "583eca88-fb46-11e1-82cb-f4ce4684ea4c",
        "sr_id": "sr:team:3415",
        "reference": "1610612763"
      },
      "player": {
        "full_name": "GG Jackson",
        "jersey_number": "45",
        "id": "28549c0f-c6e6-4757-a515-dbc2e1b78007",
        "sr_id": "sr:player:2438851",
        "reference": "1641713"
      }
    }
  ]
},
{
  "id": "cf9d8e41-be5a-4479-9d9f-250451f641b3",
  "clock": "11:04",
  "updated": "2024-04-02T01:37:26Z",
  "description": "Jalen Duren defensive rebound",
  "wall_clock": "2024-04-01T23:12:14Z",
  "sequence": 1712013133900,
  "home_points": 0,
  "away_points": 0,
  "clock_decimal": "11:04",
  "number": 13,
  "event_type": "rebound",
  "attribution": {
    "name": "Pistons",
    "market": "Detroit",
    "id": "583ec928-fb46-11e1-82cb-f4ce4684ea4c",
    "team_basket": "right",
    "sr_id": "sr:team:3424",
    "reference": "1610612765"
  },
  "location": {
    "coord_x": 297,
    "coord_y": 516,
    "action_area": "backcourt"
  },
  "possession": {
    "name": "Pistons",
    "market": "Detroit",
    "id": "583ec928-fb46-11e1-82cb-f4ce4684ea4c",
    "sr_id": "sr:team:3424",
    "reference": "1610612765"
  },
  "on_court": {
    "home": {
      "name": "Pistons",
      "market": "Detroit",
      "id": "583ec928-fb46-11e1-82cb-f4ce4684ea4c",
      "sr_id": "sr:team:3424",
      "reference": "1610612765",
      "players": [
        {
          "full_name": "Troy Brown Jr.",
          "jersey_number": "7",
          "id": "5350a897-aa31-4510-8feb-e709e1feb844",
          "sr_id": "sr:player:1320578",
          "reference": "1628972"
        },
        {
          "full_name": "Jaden Ivey",
          "jersey_number": "23",
          "id": "ec887131-efba-43a0-ad0a-0757ab3f0399",
          "sr_id": "sr:player:2077169",
          "reference": "1631093"
        },
        {
          "full_name": "Jalen Duren",
          "jersey_number": "0",
          "id": "00fb2704-aa25-4ef7-8972-cde454810810",
          "sr_id": "sr:player:2218398",
          "reference": "1631105"
        },
        {
          "full_name": "Tosan Evbuomwan",
          "jersey_number": "18",
          "id": "68ed2fac-e117-48e1-ac43-314098f600ea",
          "sr_id": "sr:player:1956598",
          "reference": "1641787"
        },
        {
          "full_name": "Cade Cunningham",
          "jersey_number": "2",
          "id": "57d55cd4-6ab8-4255-a248-bef800c0cbab",
          "sr_id": "sr:player:2068637",
          "reference": "1630595"
        }
      ]
    },
    "away": {
      "name": "Grizzlies",
      "market": "Memphis",
      "id": "583eca88-fb46-11e1-82cb-f4ce4684ea4c",
      "sr_id": "sr:team:3415",
      "reference": "1610612763",
      "players": [
        {
          "full_name": "Scotty Pippen Jr.",
          "jersey_number": "1",
          "id": "df62b7c5-faaa-4f37-a716-b7e034aa03eb",
          "sr_id": "sr:player:1831704",
          "reference": "1630590"
        },
        {
          "full_name": "Luke Kennard",
          "jersey_number": "10",
          "id": "a537047d-c29f-4dfe-99b0-3bac4e258dc7",
          "sr_id": "sr:player:1126375",
          "reference": "1628379"
        },
        {
          "full_name": "Santi Aldama",
          "jersey_number": "7",
          "id": "266cd359-f378-45c6-957e-6e21378e5219",
          "sr_id": "sr:player:1876228",
          "reference": "1630583"
        },
        {
          "full_name": "GG Jackson",
          "jersey_number": "45",
          "id": "28549c0f-c6e6-4757-a515-dbc2e1b78007",
          "sr_id": "sr:player:2438851",
          "reference": "1641713"
        },
        {
          "full_name": "Jaren Jackson Jr.",
          "jersey_number": "13",
          "id": "3e492a6a-ed3c-499d-b3f5-ff68ca16f6fd",
          "sr_id": "sr:player:1316824",
          "reference": "1628991"
        }
      ]
    }
  },
  "statistics": [
    {
      "type": "rebound",
      "rebound_type": "defensive",
      "team": {
        "name": "Pistons",
        "market": "Detroit",
        "id": "583ec928-fb46-11e1-82cb-f4ce4684ea4c",
        "sr_id": "sr:team:3424",
        "reference": "1610612765"
      },
      "player": {
        "full_name": "Jalen Duren",
        "jersey_number": "0",
        "id": "00fb2704-aa25-4ef7-8972-cde454810810",
        "sr_id": "sr:player:2218398",
        "reference": "1631105"
      }
    }
  ]
},
{
  "id": "1840f393-24d4-404e-bcde-210337ce83f3",
  "clock": "10:54",
  "updated": "2024-04-02T01:37:26Z",
  "description": "Tosan Evbuomwan makes two point driving layup (Cade Cunningham assists)",
  "wall_clock": "2024-04-01T23:12:22Z",
  "sequence": 1712013142900,
  "home_points": 2,
  "away_points": 0,
  "clock_decimal": "10:54",
  "number": 14,
  "event_type": "twopointmade",
  "qualifiers": [
    {
      "qualifier": "pointsinthepaint"
    }
  ],
  "attribution": {
    "name": "Pistons",
    "market": "Detroit",
    "id": "583ec928-fb46-11e1-82cb-f4ce4684ea4c",
    "team_basket": "right",
    "sr_id": "sr:team:3424",
    "reference": "1610612765"
  },
  "location": {
    "coord_x": 1060,
    "coord_y": 276,
    "action_area": "underbasket"
  },
  "possession": {
    "name": "Grizzlies",
    "market": "Memphis",
    "id": "583eca88-fb46-11e1-82cb-f4ce4684ea4c",
    "sr_id": "sr:team:3415",
    "reference": "1610612763"
  },
  "on_court": {
    "home": {
      "name": "Pistons",
      "market": "Detroit",
      "id": "583ec928-fb46-11e1-82cb-f4ce4684ea4c",
      "sr_id": "sr:team:3424",
      "reference": "1610612765",
      "players": [
        {
          "full_name": "Troy Brown Jr.",
          "jersey_number": "7",
          "id": "5350a897-aa31-4510-8feb-e709e1feb844",
          "sr_id": "sr:player:1320578",
          "reference": "1628972"
        },
        {
          "full_name": "Jaden Ivey",
          "jersey_number": "23",
          "id": "ec887131-efba-43a0-ad0a-0757ab3f0399",
          "sr_id": "sr:player:2077169",
          "reference": "1631093"
        },
        {
          "full_name": "Jalen Duren",
          "jersey_number": "0",
          "id": "00fb2704-aa25-4ef7-8972-cde454810810",
          "sr_id": "sr:player:2218398",
          "reference": "1631105"
        },
        {
          "full_name": "Tosan Evbuomwan",
          "jersey_number": "18",
          "id": "68ed2fac-e117-48e1-ac43-314098f600ea",
          "sr_id": "sr:player:1956598",
          "reference": "1641787"
        },
        {
          "full_name": "Cade Cunningham",
          "jersey_number": "2",
          "id": "57d55cd4-6ab8-4255-a248-bef800c0cbab",
          "sr_id": "sr:player:2068637",
          "reference": "1630595"
        }
      ]
    },
    "away": {
      "name": "Grizzlies",
      "market": "Memphis",
      "id": "583eca88-fb46-11e1-82cb-f4ce4684ea4c",
      "sr_id": "sr:team:3415",
      "reference": "1610612763",
      "players": [
        {
          "full_name": "Scotty Pippen Jr.",
          "jersey_number": "1",
          "id": "df62b7c5-faaa-4f37-a716-b7e034aa03eb",
          "sr_id": "sr:player:1831704",
          "reference": "1630590"
        },
        {
          "full_name": "Luke Kennard",
          "jersey_number": "10",
          "id": "a537047d-c29f-4dfe-99b0-3bac4e258dc7",
          "sr_id": "sr:player:1126375",
          "reference": "1628379"
        },
        {
          "full_name": "Santi Aldama",
          "jersey_number": "7",
          "id": "266cd359-f378-45c6-957e-6e21378e5219",
          "sr_id": "sr:player:1876228",
          "reference": "1630583"
        },
        {
          "full_name": "GG Jackson",
          "jersey_number": "45",
          "id": "28549c0f-c6e6-4757-a515-dbc2e1b78007",
          "sr_id": "sr:player:2438851",
          "reference": "1641713"
        },
        {
          "full_name": "Jaren Jackson Jr.",
          "jersey_number": "13",
          "id": "3e492a6a-ed3c-499d-b3f5-ff68ca16f6fd",
          "sr_id": "sr:player:1316824",
          "reference": "1628991"
        }
      ]
    }
  },
  "statistics": [
    {
      "type": "assist",
      "team": {
        "name": "Pistons",
        "market": "Detroit",
        "id": "583ec928-fb46-11e1-82cb-f4ce4684ea4c",
        "sr_id": "sr:team:3424",
        "reference": "1610612765"
      },
      "player": {
        "full_name": "Cade Cunningham",
        "jersey_number": "2",
        "id": "57d55cd4-6ab8-4255-a248-bef800c0cbab",
        "sr_id": "sr:player:2068637",
        "reference": "1630595"
      }
    },
    {
      "type": "fieldgoal",
      "made": true,
      "shot_type": "layup",
      "shot_type_desc": "driving",
      "points": 2,
      "shot_distance": 2.04,
      "team": {
        "name": "Pistons",
        "market": "Detroit",
        "id": "583ec928-fb46-11e1-82cb-f4ce4684ea4c",
        "sr_id": "sr:team:3424",
        "reference": "1610612765"
      },
      "player": {
        "full_name": "Tosan Evbuomwan",
        "jersey_number": "18",
        "id": "68ed2fac-e117-48e1-ac43-314098f600ea",
        "sr_id": "sr:player:1956598",
        "reference": "1641787"
      }
    }
  ]
}

In this play-by-play example, GG Jackson of the Memphis Grizzlies misses a three-point jump shot from the left side of the court, leading to a defensive rebound by Jalen Duren of the Detroit Pistons. The Pistons capitalize on the possession when Tosan Evbuomwan makes a driving layup, assisted by Cade Cunningham. This sequence highlights key events such as missed shots, rebounds, assists, and made baskets, capturing the flow of the game and providing real-time stats for analysis.

You can visualize this play-by-play sequence in your application by creating a graphic that mirrors the flow of the game. This visual can capture missed shots, rebounds, turnovers, and scoring plays.


Use Case:

In your basketball analytics application, you could track and display detailed play-by-play data like the missed three-point shot by GG Jackson of the Memphis Grizzlies. For instance, you can analyze his attempt from 26.54 feet and follow it up with Jalen Duren's defensive rebound for the Detroit Pistons. Displaying this sequence allows users to assess shooting efficiency, defensive rebounds, and key moments in the game flow. This information is critical for evaluating player performance and can be particularly valuable for making informed decisions in fantasy basketball leagues or game strategy analysis.


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.

👍

Tip - Compare Data Points

Compare the data points returned by the 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 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 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 NBA games.
  • The Push Events feed should not be used exclusively; supplement it with the 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 basketball tracking app, you might use the Push Events feed to receive real-time notifications of key moments like dunks, fouls, or three-pointers. However, for a user-requested feature that provides a detailed timeline of the game, including minor plays and player stats, you can supplement with the Play-by-Play feed to capture comprehensive game details beyond quick updates. This ensures your app delivers both instant highlights and in-depth analysis.

📘

Game Status Workflows

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


Bonus - Using the Push Clock Feed

In addition to live play-by-play data, you can utilize the Push Clock feed to fetch NBA game clock updates, providing access to live game timing information.


How to Pull the Push Clock Feed:

  1. Open a connection with a single call to the Push Clock feed to receive real-time updates.
  2. Add the match parameter with the specific game id. Without the match parameter the feed will return data for all live NBA games.
  3. In the event of a disconnection from the Push Clock feed, it's not possible to resume where you left off. To ensure continuous coverage, use multiple Push Feeds

Use Case:

You can use this real-time clock data to enhance your sports app by providing live game updates that keep users engaged. For instance, you can display the remaining game and shot clock times, show when the clock is running or paused, and highlight critical moments such as the final seconds of a quarter or overtime period.


Scoring Updates

If your main interest is live score updates, use the Game Boxscore feed. While the Play-by-Play and Push Events feeds also include scoring data, the Game Boxscore feed offers more detailed scoring information for each team.


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.
🏀
Accessing NBA Game Boxscore Data
Open Recipe

Game Boxscore Example:

{
"scoring": [
      {
        "type": "quarter",
        "number": 1,
        "sequence": 1,
        "points": 19
      },
      {
        "type": "quarter",
        "number": 2,
        "sequence": 2,
        "points": 24
      },
      {
        "type": "quarter",
        "number": 3,
        "sequence": 3,
        "points": 32
      },
      {
        "type": "quarter",
        "number": 4,
        "sequence": 4,
        "points": 30
      }
    ],
    "leaders": {
      "points": [
        {
          "full_name": "Kyle Kuzma",
          "jersey_number": "33",
          "id": "4fae86e2-4f99-4247-af85-d917b4389d31",
          "position": "F",
          "primary_position": "PF",
          "sr_id": "sr:player:1142582",
          "reference": "1628398",
          "statistics": {
            "minutes": "31:47",
            "field_goals_made": 10,
            "field_goals_att": 21,
            "field_goals_pct": 47.6,
            "three_points_made": 4,
            "three_points_att": 10,
            "three_points_pct": 40,
            "two_points_made": 6,
            "two_points_att": 11,
            "two_points_pct": 54.5,
            "blocked_att": 1,
            "free_throws_made": 3,
            "free_throws_att": 4,
            "free_throws_pct": 75,
            "offensive_rebounds": 0,
            "defensive_rebounds": 2,
            "rebounds": 2,
            "assists": 2,
            "turnovers": 3,
            "steals": 0,
            "blocks": 1,
            "assists_turnover_ratio": 0.67,
            "personal_fouls": 3,
            "tech_fouls": 0,
            "flagrant_fouls": 0,
            "pls_min": -8,
            "points": 27,
            "tech_fouls_non_unsportsmanlike": 0,
            "double_double": false,
            "triple_double": false,
            "effective_fg_pct": 57.1,
            "efficiency": 16,
            "efficiency_game_score": 14.4,
            "fouls_drawn": 3,
            "offensive_fouls": 1,
            "points_in_paint": 10,
            "points_in_paint_att": 9,
            "points_in_paint_made": 5,
            "points_in_paint_pct": 55.6,
            "points_off_turnovers": 4,
            "true_shooting_att": 22.76,
            "true_shooting_pct": 59.3,
            "coach_ejections": 0,
            "coach_tech_fouls": 0,
            "second_chance_pts": 3,
            "second_chance_pct": 50
          }
        }
      ],
      "rebounds": [
        {
          "full_name": "Daniel Gafford",
          "jersey_number": "21",
          "id": "52cd8137-c791-4569-ad70-433e25d34882",
          "position": "C",
          "primary_position": "C",
          "sr_id": "sr:player:1286466",
          "reference": "1629655",
          "statistics": {
            "minutes": "30:38",
            "field_goals_made": 2,
            "field_goals_att": 2,
            "field_goals_pct": 100,
            "three_points_made": 0,
            "three_points_att": 0,
            "three_points_pct": 0,
            "two_points_made": 2,
            "two_points_att": 2,
            "two_points_pct": 100,
            "blocked_att": 0,
            "free_throws_made": 2,
            "free_throws_att": 4,
            "free_throws_pct": 50,
            "offensive_rebounds": 4,
            "defensive_rebounds": 8,
            "rebounds": 12,
            "assists": 3,
            "turnovers": 1,
            "steals": 1,
            "blocks": 1,
            "assists_turnover_ratio": 3,
            "personal_fouls": 5,
            "tech_fouls": 0,
            "flagrant_fouls": 0,
            "pls_min": -8,
            "points": 6,
            "tech_fouls_non_unsportsmanlike": 1,
            "double_double": false,
            "triple_double": false,
            "effective_fg_pct": 100,
            "efficiency": 18,
            "efficiency_game_score": 10.6,
            "fouls_drawn": 4,
            "offensive_fouls": 0,
            "points_in_paint": 4,
            "points_in_paint_att": 2,
            "points_in_paint_made": 2,
            "points_in_paint_pct": 100,
            "points_off_turnovers": 0,
            "true_shooting_att": 3.76,
            "true_shooting_pct": 79.8,
            "coach_ejections": 0,
            "coach_tech_fouls": 0,
            "second_chance_pts": 3,
            "second_chance_pct": 100
          }
        }
      ]
    }
  }

This Game Boxscore example highlights key player performances and quarter-by-quarter scoring. Kyle Kuzma led the Wizards with 27 points, shooting 47.6% from the field, while Daniel Gafford contributed 12 rebounds. The Wizards scored 19, 24, 32, and 30 points in each quarter, showcasing the team’s increasing offensive output as the game progressed. This detailed breakdown provides a quick overview of individual and team contributions throughout the game.

This is how you can display boxscore data for a game summary. The visual highlights a final score of 121-105 between the New York Knicks and Washington Wizards, showing team logos, records, attendance, and a breakdown of points per quarter. The concise format provides a clear overview of the game, allowing users to quickly grasp the outcome and scoring trends at a glance.


📸

Accessing Headshots and Team Logos

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


Use Case:

You can use this player performance data to enhance your sports app by offering detailed breakdowns of key moments in the game. You can display individual player stats, such as scoring contributions, rebounds, and assists, allowing users to see how each player's efforts influenced the game's outcome. Additionally, you can provide insights into shooting efficiency, defensive plays, and player matchups, helping users understand how these factors shaped critical turning points.


Game Statistics

If you're looking for game statistics like points scored, rebounds, and assists, you can use the Game Summary feed. In addition to Boxscore information, this feed provides detailed game stats at the team and player levels, offering a comprehensive view of key performance metrics throughout the game.


Option 1 - Using the Game Summary Feed

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


How to Pull the Game Summary 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 Summary Example:

{
"away": {
    "name": "Knicks",
    "alias": "NYK",
    "market": "New York",
    "id": "583ec70e-fb46-11e1-82cb-f4ce4684ea4c",
    "points": 121,
    "bonus": true,
    "sr_id": "sr:team:3421",
    "remaining_timeouts": 2,
    "reference": "1610612752",
    "record": {
      "wins": 50,
      "losses": 32
    },
    "scoring": [
      {
        "type": "quarter",
        "number": 1,
        "sequence": 1,
        "points": 34
      },
      {
        "type": "quarter",
        "number": 2,
        "sequence": 2,
        "points": 29
      },
      {
        "type": "quarter",
        "number": 3,
        "sequence": 3,
        "points": 28
      },
      {
        "type": "quarter",
        "number": 4,
        "sequence": 4,
        "points": 30
      }
    ],
    "statistics": {
      "minutes": "4:00:00",
      "field_goals_made": 43,
      "field_goals_att": 87,
      "field_goals_pct": 49.4,
      "three_points_made": 14,
      "three_points_att": 36,
      "three_points_pct": 38.9,
      "two_points_made": 29,
      "two_points_att": 51,
      "two_points_pct": 56.9,
      "blocked_att": 3,
      "free_throws_made": 21,
      "free_throws_att": 24,
      "free_throws_pct": 87.5,
      "offensive_rebounds": 11,
      "defensive_rebounds": 34,
      "assists": 27,
      "steals": 9,
      "blocks": 2,
      "assists_turnover_ratio": 1.93,
      "personal_fouls": 16,
      "ejections": 0,
      "foulouts": 0,
      "points": 121,
      "fast_break_pts": 20,
      "second_chance_pts": 20,
      "team_turnovers": 0,
      "points_off_turnovers": 23,
      "team_rebounds": 4,
      "flagrant_fouls": 0,
      "player_tech_fouls": 0,
      "team_tech_fouls": 0,
      "coach_tech_fouls": 0,
      "points_in_paint": 52,
      "team_offensive_rebounds": 2,
      "team_defensive_rebounds": 2,
      "total_rebounds": 49,
      "total_turnovers": 14,
      "personal_rebounds": 45,
      "player_turnovers": 14,
      "field_goals_at_rim_made": 18,
      "field_goals_at_rim_att": 21,
      "field_goals_at_rim_pct": 85.7,
      "field_goals_at_midrange_made": 3,
      "field_goals_at_midrange_att": 9,
      "field_goals_at_midrange_pct": 33.3,
      "bench_points": 22,
      "biggest_lead": 26,
      "effective_fg_pct": 57.5,
      "efficiency": 144,
      "efficiency_game_score": 102.9,
      "fouls_drawn": 20,
      "offensive_fouls": 1,
      "pls_min": 16,
      "points_in_paint_att": 42,
      "points_in_paint_made": 26,
      "points_in_paint_pct": 61.9,
      "total_fouls": 16,
      "true_shooting_att": 97.56,
      "true_shooting_pct": 62,
      "coach_ejections": 0,
      "defensive_rating": 103.143418467584,
      "offensive_rating": 120.326173428799,
      "points_against": 105,
      "possessions": 100.56,
      "opponent_possessions": 101.8,
      "time_leading": "47:42",
      "defensive_points_per_possession": 1.04,
      "offensive_points_per_possession": 1.2,
      "team_fouls": 0,
      "second_chance_att": 9,
      "second_chance_made": 8,
      "second_chance_pct": 88.9,
      "fast_break_att": 13,
      "fast_break_made": 10,
      "fast_break_pct": 76.9,
      "most_unanswered": {
        "points": 9,
        "own_score": 32,
        "opp_score": 18
      },
      "periods": [
        {
          "type": "REG",
          "id": "ebe64044-f1c5-4342-85f8-a5fffa5b1406",
          "number": 1,
          "sequence": 1,
          "minutes": "1:00:00",
          "field_goals_made": 12,
          "field_goals_att": 22,
          "field_goals_pct": 54.5,
          "three_points_made": 5,
          "three_points_att": 10,
          "three_points_pct": 50,
          "two_points_made": 7,
          "two_points_att": 12,
          "two_points_pct": 58.3,
          "blocked_att": 0,
          "free_throws_made": 5,
          "free_throws_att": 6,
          "free_throws_pct": 83.3,
          "offensive_rebounds": 4,
          "defensive_rebounds": 9,
          "rebounds": 13,
          "assists": 8,
          "turnovers": 4,
          "steals": 5,
          "blocks": 0,
          "assists_turnover_ratio": 2,
          "personal_fouls": 3,
          "offensive_fouls": 0,
          "points": 34,
          "fast_break_pts": 6,
          "second_chance_pts": 6,
          "team_turnovers": 0,
          "points_off_turnovers": 7,
          "team_rebounds": 1,
          "flagrant_fouls": 0,
          "player_tech_fouls": 0,
          "team_tech_fouls": 0,
          "coach_tech_fouls": 0,
          "pls_min": 15,
          "effective_fg_pct": 65.9,
          "bench_points": 2,
          "points_in_paint": 14,
          "points_in_paint_att": 11,
          "points_in_paint_made": 7,
          "points_in_paint_pct": 63.6,
          "true_shooting_att": 24.64,
          "true_shooting_pct": 69,
          "biggest_lead": 15,
          "fouls_drawn": 5,
          "total_turnovers": 4,
          "efficiency": 47,
          "efficiency_game_score": 33.9,
          "team_defensive_rebounds": 1,
          "team_offensive_rebounds": 0,
          "total_fouls": 3,
          "total_rebounds": 14,
          "defensive_rating": 76.7366720516963,
          "offensive_rating": 137.987012987013,
          "points_against": 19,
          "possessions": 24.64,
          "opponent_possessions": 24.76,
          "time_leading": "11:42",
          "defensive_points_per_possession": 0.77,
          "offensive_points_per_possession": 1.38,
          "team_fouls": 0,
          "second_chance_att": 3,
          "second_chance_made": 3,
          "second_chance_pct": 100,
          "fast_break_att": 3,
          "fast_break_made": 3,
          "fast_break_pct": 100
        },
        {
          "type": "REG",
          "id": "7aea0a31-190f-4813-8985-6261ea433c9f",
          "number": 2,
          "sequence": 2,
          "minutes": "1:00:00",
          "field_goals_made": 10,
          "field_goals_att": 20,
          "field_goals_pct": 50,
          "three_points_made": 2,
          "three_points_att": 8,
          "three_points_pct": 25,
          "two_points_made": 8,
          "two_points_att": 12,
          "two_points_pct": 66.7,
          "blocked_att": 2,
          "free_throws_made": 7,
          "free_throws_att": 7,
          "free_throws_pct": 100,
          "offensive_rebounds": 3,
          "defensive_rebounds": 9,
          "rebounds": 12,
          "assists": 6,
          "turnovers": 6,
          "steals": 3,
          "blocks": 1,
          "assists_turnover_ratio": 1,
          "personal_fouls": 8,
          "offensive_fouls": 1,
          "points": 29,
          "fast_break_pts": 10,
          "second_chance_pts": 4,
          "team_turnovers": 0,
          "points_off_turnovers": 12,
          "team_rebounds": 0,
          "flagrant_fouls": 0,
          "player_tech_fouls": 0,
          "team_tech_fouls": 0,
          "coach_tech_fouls": 0,
          "pls_min": 5,
          "effective_fg_pct": 55,
          "bench_points": 10,
          "points_in_paint": 14,
          "points_in_paint_att": 10,
          "points_in_paint_made": 7,
          "points_in_paint_pct": 70,
          "true_shooting_att": 23.08,
          "true_shooting_pct": 62.8,
          "biggest_lead": 26,
          "fouls_drawn": 3,
          "total_turnovers": 6,
          "efficiency": 28,
          "efficiency_game_score": 22.5,
          "team_defensive_rebounds": 0,
          "team_offensive_rebounds": 0,
          "total_fouls": 8,
          "total_rebounds": 12,
          "defensive_rating": 89.0207715133531,
          "offensive_rating": 111.196319018405,
          "points_against": 24,
          "possessions": 26.08,
          "opponent_possessions": 26.96,
          "time_leading": "12:00",
          "defensive_points_per_possession": 0.92,
          "offensive_points_per_possession": 1.11,
          "team_fouls": 0,
          "second_chance_att": 1,
          "second_chance_made": 1,
          "second_chance_pct": 100,
          "fast_break_att": 7,
          "fast_break_made": 5,
          "fast_break_pct": 71.4
        },
        {
          "type": "REG",
          "id": "33c6368d-120a-40cd-9c3b-7098495d3db8",
          "number": 3,
          "sequence": 3,
          "minutes": "1:00:00",
          "field_goals_made": 9,
          "field_goals_att": 21,
          "field_goals_pct": 42.9,
          "three_points_made": 3,
          "three_points_att": 9,
          "three_points_pct": 33.3,
          "two_points_made": 6,
          "two_points_att": 12,
          "two_points_pct": 50,
          "blocked_att": 1,
          "free_throws_made": 7,
          "free_throws_att": 8,
          "free_throws_pct": 87.5,
          "offensive_rebounds": 0,
          "defensive_rebounds": 6,
          "rebounds": 6,
          "assists": 7,
          "turnovers": 2,
          "steals": 1,
          "blocks": 0,
          "assists_turnover_ratio": 3.5,
          "personal_fouls": 1,
          "offensive_fouls": 0,
          "points": 28,
          "fast_break_pts": 2,
          "second_chance_pts": 3,
          "team_turnovers": 0,
          "points_off_turnovers": 4,
          "team_rebounds": 3,
          "flagrant_fouls": 0,
          "player_tech_fouls": 0,
          "team_tech_fouls": 0,
          "coach_tech_fouls": 0,
          "pls_min": -4,
          "effective_fg_pct": 50,
          "bench_points": 0,
          "points_in_paint": 10,
          "points_in_paint_att": 10,
          "points_in_paint_made": 5,
          "points_in_paint_pct": 50,
          "true_shooting_att": 24.52,
          "true_shooting_pct": 57.1,
          "biggest_lead": 20,
          "fouls_drawn": 7,
          "total_turnovers": 2,
          "efficiency": 32,
          "efficiency_game_score": 21.8,
          "team_defensive_rebounds": 1,
          "team_offensive_rebounds": 2,
          "total_fouls": 1,
          "total_rebounds": 9,
          "defensive_rating": 119.047619047619,
          "offensive_rating": 105.580693815988,
          "points_against": 32,
          "possessions": 26.52,
          "opponent_possessions": 26.88,
          "time_leading": "12:00",
          "defensive_points_per_possession": 1.21,
          "offensive_points_per_possession": 1.06,
          "team_fouls": 0,
          "second_chance_att": 1,
          "second_chance_made": 1,
          "second_chance_pct": 100,
          "fast_break_att": 1,
          "fast_break_made": 1,
          "fast_break_pct": 100
        },
        {
          "type": "REG",
          "id": "bf439639-8435-457d-a012-173c89d2ef95",
          "number": 4,
          "sequence": 4,
          "minutes": "1:00:00",
          "field_goals_made": 12,
          "field_goals_att": 24,
          "field_goals_pct": 50,
          "three_points_made": 4,
          "three_points_att": 9,
          "three_points_pct": 44.4,
          "two_points_made": 8,
          "two_points_att": 15,
          "two_points_pct": 53.3,
          "blocked_att": 0,
          "free_throws_made": 2,
          "free_throws_att": 3,
          "free_throws_pct": 66.7,
          "offensive_rebounds": 4,
          "defensive_rebounds": 10,
          "rebounds": 14,
          "assists": 6,
          "turnovers": 2,
          "steals": 0,
          "blocks": 1,
          "assists_turnover_ratio": 3,
          "personal_fouls": 4,
          "offensive_fouls": 0,
          "points": 30,
          "fast_break_pts": 2,
          "second_chance_pts": 7,
          "team_turnovers": 0,
          "points_off_turnovers": 0,
          "team_rebounds": 0,
          "flagrant_fouls": 0,
          "player_tech_fouls": 0,
          "team_tech_fouls": 0,
          "coach_tech_fouls": 0,
          "pls_min": 0,
          "effective_fg_pct": 58.3,
          "bench_points": 10,
          "points_in_paint": 14,
          "points_in_paint_att": 11,
          "points_in_paint_made": 7,
          "points_in_paint_pct": 63.6,
          "true_shooting_att": 25.32,
          "true_shooting_pct": 59.2,
          "biggest_lead": 23,
          "fouls_drawn": 5,
          "total_turnovers": 2,
          "efficiency": 37,
          "efficiency_game_score": 24.7,
          "team_defensive_rebounds": 0,
          "team_offensive_rebounds": 0,
          "total_fouls": 4,
          "total_rebounds": 14,
          "defensive_rating": 129.310344827586,
          "offensive_rating": 128.644939965695,
          "points_against": 30,
          "possessions": 23.32,
          "opponent_possessions": 23.2,
          "time_leading": "12:00",
          "defensive_points_per_possession": 1.29,
          "offensive_points_per_possession": 1.29,
          "team_fouls": 0,
          "second_chance_att": 4,
          "second_chance_made": 3,
          "second_chance_pct": 75,
          "fast_break_att": 2,
          "fast_break_made": 1,
          "fast_break_pct": 50
        }
      ]
    }
  }
}

In this example of the New York Knicks, the statistics include total points scored, field goal percentages, three-point shooting efficiency, and key metrics like rebounds, assists, and turnovers. Additionally, the data covers points in the paint, fast break points, and second-chance points, providing a comprehensive overview of the team's offensive and defensive performance. These detailed stats help in analyzing the Knicks' game strategies, player efficiency, and overall team execution throughout the game.

You can visually represent key game statistics in your applications, showcasing essential data like field goal percentages, rebounds, and fouls. This style of presentation is ideal for conveying game insights to users in a clear and engaging way.



Use Case

You can use game statistics in your app to allow coaches and sports analysts to evaluate team performance and efficiency. This data provides valuable insights into field goal percentages, time spent in the lead, and the largest scoring runs, offering a clear understanding of how the game unfolded. By analyzing metrics such as rebounding, fouls, and shooting efficiency, users can make informed decisions on player rotations and strategies.


Option 2 - Using the Push Statistics Feed

The Push Statistics feed offers the same live stat data as the Game Summary 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 Summary 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 NBA games.
  • In the event of a disconnection from the Push Statistics 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 the Game Summary feed as a fallback to retrieve any missed timeline information during live games.

All-Star Game FAQ

How do I locate the All-Star game?

The game can be found in the Daily Schedule feed on the date of the event. For example: nba/trial/v8/en/games/2024/02/18/schedule

Every game-centric feed (e.g. Game Play-by-Play, Game Summary, Push Events, etc) can be accessed during the game.

Click here for for a Game Summary or Play-by-Play sample of the 2022 game.

What are the differences from a typical NBA game?

All-Star teams represent the Eastern and Western Conferences, with their own unique Ids. Conference team Ids will be consistent for each year beginning in 2024.

Please note that these teams will not be included in the League Hierarchy endpoint.

2024 Teams:

<home name="East NBA All Stars" alias="EST" id="592d3144-895b-43e9-ab15-e84666a845d5" reference="1610616833">

<away name="West NBA All Stars" alias="WST" id="787ff06f-f0cc-484e-8114-04e0cdc444fa" reference="1610616834">

Is the All-Star game covered in realtime?

Yes. The game is covered in realtime, including the same level of team and player statistics as a regular season game.

When are the All-Star rosters set?

All-Star game rosters will be available shortly prior to tipoff.

Please note that we only provide game rosters (not team rosters) for each game. Request the Game Summary endpoint prior to the game to receive rosters.

If you require rosters earlier, we suggest using the Team Profile endpoints of each NBA team to pull in players manually.

Do you cover any of the other All-Star game events?

No. We currently only cover the NBA All-Star game in the NBA API.






Game Simulations

Our API simulations allow you to replay actual games at any time, on your own schedule.

With the replayer, you can:

  • Request a list of available recordings (by league)
  • Register a session (allows a game to be replayed in natural time, specific to the session)
  • Continually request an endpoint as a "live" game progresses
  • Open up a continuous Push simulation of a game

Failover Data

The NBA API data is collected by an NBA-trained stats team and processed by Sportradar. If the NBA experiences an unexpected system failure, Sportradar's failover process seamlessly takes over, ensuring your client application continues to receive data. While this prevents a total loss of data, some coverage differences may occur.

Please note that when the game is over, all data entered by Sportradar is deleted and replaced with the official data provided by the NBA.


Official Data Unavailable During Failover

Boxscore Information:

  • Only Head Coach attributes are available - All other team staff members will not be displayed.
  • Not playing reason.

Game Statistics - Team:

  • Defensive Points per Possession
  • Defensive Rating
  • Fast Break Attempts
  • Fast Break Made
  • Fast Break Percentage
  • Offensive Points per Possession
  • Offensive Rating
  • Opponent Possessions
  • Points Against
  • Possessions
  • Second Chance Attempts
  • Second Chance Made
  • Second Chance Percentage
  • Team Defensive Rebounds
  • Team Fouls
  • Team Offensive Rebounds
  • Time Leadings
  • Total Fouls
  • Total Rebounds

.

Game Statistics - Player:

  • Coach Ejections
  • Coach Technical Fouls
  • Defensive Rating
  • Defensive Rebounds Percentage
  • Fast Break Attempts
  • Fast Break Made
  • Fast Break Percentage
  • Minus
  • Offensive Rating
  • Offensive Rebounds Percentage
  • Plus
  • Rebounds Percentage
  • Second Chance Attempts
  • Second Chance Made
  • Second Chance Percentage
  • Turnovers Percentage

.

Failover Statistics Summary

See a summarized view of our failover statistics.


Daily Change Log

The Daily Change Log endpoint allows for efficient tracking of daily changes to the NBA API without depleting your API call limits. It updates you on significant changes like schedule adjustments, game results, player profile updates, and team modifications.

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

DataUse Case
Play-by-PlayTrack changes in play details such as new plays added or corrections to existing play records.
Game SummaryMonitor updates in player and team statistics or post-game corrections.
Game BoxscoreMonitor adjustments in game summary data, including final scores or statistical errors being rectified.

To use the Daily Change Log feed for monitoring changes to recent games:

  1. Identify Change Types: First, review the Daily Change Log to identify the types of changes reported. These could be related to games, players, or teams. Each entry in the log will list relevant IDs (game, player, or team ID), depending on the type of change.

  2. Use IDs to Retrieve Specifics:

    • Game Changes: If the ID is found within the "results" node, it typically indicates a change in game results. This ID is a game ID.
    • Player and Team Changes: Similarly, IDs associated with players or teams indicate changes relevant to these entities, such as updates to player information or team rosters.

  3. Pull Detailed Data: Use the identified IDs to pull detailed information from the relevant feed. For example:

    • Play-by-Play Feed: If a game ID is mentioned, you can pull this feed to check for any new plays added or modifications to existing plays.
    • Game Statistics Feed: Use the game ID to retrieve updated player statistics and team performance metrics to see what specific data was altered.
    • Game Boxscore Feed: Pull this feed using the game ID to review any updates to the game summary, including scores and other significant game statistics.

  4. Verify Changes: After pulling the detailed data from the relevant feeds, compare the newly retrieved data against previously stored data to verify the changes and update your records accordingly.


⏱️

Update Frequency

TTL / Cache: 300 seconds

Data Updates:

  • Entries populate live for changes to teams, players, game statistics, schedules, and standings.
  • Start time of the log is 05:00:00 UTC; end time is 04:59:59 UTC

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

Updated about 1 month ago

© Sportradar AG, St. Gallen, Switzerland