ID Handling

Every entity in the NBA G League API (league, season, team, player, game, series) is addressed by a GUID, and the feeds also carry the official league identifiers alongside. This page covers both ID families, how they connect, and what to key your storage on.

GUIDs Are the Primary Key

The path parameters of every entity-scoped feed ({game_id}, {team_id}, {player_id}, {series_id}) take GUIDs, and the same GUID identifies the same entity in every feed. The Greensboro Swarm are e74de5ce-3e98-4414-afe5-b56a90e527a2 in Teams, in Standings, in the Schedule's game entries, in Series Schedule participants, and in the Team Profile path.

GUIDs are stable: store them as your primary keys and treat every other identifier as an attribute. One timing exception: a player row can briefly appear without an id, mostly in preseason games when a newly added player has not yet been mapped; regular-season cases resolve before the game starts. Handle the field as optional in game payloads; see the G League FAQ.

The reference Bridge

Teams, players, and games also carry a reference: the official NBA G League identifier for the same entity. Two entries from the Teams feed:

GET https://api.sportradar.com/nbdl/trial/v8/en/league/teams.json
x-api-key: YOUR_API_KEY

{
  "league": {
    "id": "ac79301f-9b1a-4e72-a4cb-230d4418ae08",
    "name": "NBA G League",
    "alias": "NBDL"
  },
  "teams": [
    {
      "id": "e74de5ce-3e98-4414-afe5-b56a90e527a2",
      "name": "Swarm",
      "alias": "GBO",
      "market": "Greensboro",
      "reference": "1612709922"
    },
    {
      "id": "c2cab657-7b82-457c-b88c-385205d2fef4",
      "name": "TBD",
      "alias": "TBD",
      "market": "Team"
    }
  ]
}

Use reference when reconciling against official league sources. Note the second entry: the Teams list includes a placeholder team (TBD) used where a schedule slot's participant is not yet determined; filter it out of team pickers, and expect it to carry no reference.

Player References Across Leagues

Player profiles carry a references array that goes further: alongside the G League reference, it can link the same person's identity in other scopes. The profile of the player who led the 2025-26 regular season in total minutes:

GET https://api.sportradar.com/nbdl/trial/v8/en/players/761260a9-4cf6-43b9-a78e-df628a1da8b5/profile.json
x-api-key: YOUR_API_KEY

{
  "id": "761260a9-4cf6-43b9-a78e-df628a1da8b5",
  "full_name": "Jahmyl Telfort",
  "reference": "1643141",
  "references": [
    {
      "source_id": "1643141",
      "scope": "NBDL",
      "id_type": "external"
    },
    {
      "source_id": "8c65986e-fbec-401e-a5a7-384f08f24fc2",
      "scope": "basketball",
      "id_type": "sport_profile"
    },
    {
      "source_id": "0e960f68-4dfe-4dc3-bd18-16cc7ad64168",
      "scope": "NBA",
      "id_type": "league_profile"
    },
    {
      "source_id": "07475c0e-dacb-4065-8211-60cda0b63efd",
      "scope": "NCAAM",
      "id_type": "league_profile"
    }
  ],
  "team": {
    "id": "80411a5b-5ac0-4297-a19d-2dff8e0b611b",
    "name": "Clippers",
    "market": "San Diego",
    "alias": "SDC",
    "reference": "1612709924"
  }
}

Each entry pairs a source_id with a scope and an id_type:

• scope: "NBDL" with id_type: "external" is the official G League identifier (the same value as the top-level reference)
• scope: "basketball" with id_type: "sport_profile" is a basketball-wide profile GUID present for every player; it ties the same person's records together across the U.S. basketball league APIs
• id_type: "league_profile" entries carry the player's profile GUID in a league-specific basketball API (NBA and NCAAM in the sample), one for each league where the player has a record

Because G League rosters change constantly (call-ups, assignments, and two-way movement between the G League and the NBA), the references array is the reliable way to connect a player's G League record with their identity elsewhere.

Where Each ID Family Lives

Choosing Storage Keys

• Key teams, players, games, and series on their GUIDs
• Store reference and the references entries as attributes for reconciliation with league sources
• Key standings rows on the pair of season ID and team ID: the same team appears in its conference table, its division table, and (separately) the Showcase Cup table
• Key player-season statistics on the triple of player, season, and team: a player who changes teams mid-season has one entry per team

Best Practices

• Never parse meaning out of a GUID; treat IDs as opaque strings
• Detect ID-level changes (new players, corrected records) from the daily change log (Monitoring Data Changes) rather than by re-crawling entity feeds
• Filter the TBD placeholder team wherever you render team lists