Finding Games

GET /available_game_periods

Lists every game and period that has video, and which periods can be clipped by timestamp. Games with an NBA game ID can be passed as game_id_nba straight to the /clip, /period, and CSV playlist endpoints without calling this first. Use it to find the video game_id for older G League and Summer League games that have no NBA game ID.

Results are sorted by game date, oldest first, then by game and period. There is one result for each game and period.

Parameters

All parameters are optional filters.

Parameter	Type	Description
league	string	NBA, GLEAGUE, or NBASL
date	date (YYYY-MM-DD)	Games played on this date
start_date	date (YYYY-MM-DD)	Games played on or after this date
end_date	date (YYYY-MM-DD)	Games played on or before this date
home_team	string	Home team, such as BOS (exact match)
away_team	string	Away team, such as LAL (exact match)
wall_clock_timing_available	true or false	Only periods that can, or cannot, be clipped by timestamp. See Video Metrics

Without a date filter the response includes every season, so filter by date when you can.

NBA and Summer League teams use three-letter abbreviations, such as BOS. G League games also use these abbreviations for the 2023-24 season and beyond. Prior to that, they could use either the abbreviations or full names in capitals, such as WISCONSIN HERD. If a team filter returns nothing, filter by date and read the team names from the results.

Response

The response is a list of objects with these fields:

Field	Type	Description
game_id	UUID	Video game ID. Other Video API endpoints accept this or game_id_nba
game_id_nba	string or null	NBA game ID, matching game_id_nba in the data feed. Some older G League and Summer League games have null here
period	integer	Period number. Overtime periods continue from 5
game_info.id	UUID	Same as game_id
game_info.game_id_nba	string or null	Same as game_id_nba
game_info.league	string	NBA, GLEAGUE, or NBASL
game_info.game_date	date (YYYY-MM-DD)	Local date of the game
game_info.home_team	string	Home team
game_info.away_team	string	Away team
video_metrics	list	Video coverage details. Always contains one entry (see below)

Video Metrics

Field	Type	Description
wall_clock_timing_available	boolean	true when clips for this period can be requested by start_timestamp. When false, request clips by start_game_clock. See Game Clock or Timestamp
has_precise_frame_alignment	boolean	true when the video has been aligned to the tracking wall clock to within about a tenth of a second. Returned for every league
reliability	string or null	How reliably clips match the requested time (see below). null when wall_clock_timing_available is true, because clips then use tracking data instead of the on-screen clock
first_time	number or null	First game clock time with video, in seconds left in the period. null when reliability is null. Clips before this time fail

For G League and Summer League games that we do not have associated tracking data for, the API gives responses based on reading the clock off the screen. Sometimes this can have issues or coverage gaps, particularly if the video quality is poor of the clock is not always available. The reliability indicator gives you a sense of how well we processed this period. The values is one of:

Value	Meaning
Very Good	Expect very few, if any, incorrect clips
Good	Most clips are correct, but a few short stretches of the period may be off
Medium	Expect several short stretches, or one long stretch, of incorrect clips
Poor	Expect many incorrect clips

NOTE

When G League or Summer League games have tracking data, we use that data to return the clips, and reliability and first_time are null. This only matters for games in which we do not have tracking data.

A period's video can be aligned to tracking data after it is first published. When that happens, wall_clock_timing_available changes from false to true.

Example

curl --request GET \
  --url 'https://api.cleaningtheglass.com/video/available_game_periods?league=NBA&date=2024-10-30&home_team=WAS' \
  --header 'X-API-KEY: YOUR_VIDEO_API_KEY'

[
  {
    "game_id": "00124539-08e3-4174-bd7f-db5e96a904fb",
    "game_id_nba": "0022400121",
    "game_info": {
      "away_team": "ATL",
      "game_date": "2024-10-30",
      "game_id_nba": "0022400121",
      "home_team": "WAS",
      "id": "00124539-08e3-4174-bd7f-db5e96a904fb",
      "league": "NBA"
    },
    "period": 1,
    "video_metrics": [
      {
        "first_time": null,
        "has_precise_frame_alignment": true,
        "reliability": null,
        "wall_clock_timing_available": true
      }
    ]
  }
]

Matching a Data Feed Game

Pass the data feed's game_id_nba directly to the other endpoints. To check whether a game has video, or whether its periods support timestamps, filter by its date and home team and pick the result whose game_id_nba matches.

If you only need clips of data feed markings, skip this step and create a playlist from marking IDs.