---
updatedAt: 2026-09-01T10:23:13.000Z
agentTools:
  siteIndex: https://developer.sportradar.com/llms.txt
  projectIndex: https://developer.sportradar.com/basketball/llms.txt
---

# 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.

<br />

***

## 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](https://developer.sportradar.com/basketball/reference/g-league-faq#why-is-a-player-missing-a-playerid-in-a-game).

<br />

***

## 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 <Anchor label="Teams" target="_blank" href="ref:g-league-teams">Teams</Anchor> feed:

```http
GET https://api.sportradar.com/nbdl/trial/v8/en/league/teams.json
x-api-key: YOUR_API_KEY
```
```json Teams (json)
{
  "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`.

<br />

***

## 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:

```http
GET https://api.sportradar.com/nbdl/trial/v8/en/players/761260a9-4cf6-43b9-a78e-df628a1da8b5/profile.json
x-api-key: YOUR_API_KEY
```
```json Player Profile (json)
{
  "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.

<br />

***

## Where Each ID Family Lives

<div style={{border: "1px solid #C5CAE9", borderRadius: "12px", overflow: "hidden", margin: "4px 0 8px"}}>
  <div style={{background: "linear-gradient(90deg, #1A237E 0%, #283593 60%, #3949AB 100%)", color: "#FFFFFF", padding: "10px 18px", display: "flex", alignItems: "baseline", justifyContent: "space-between", flexWrap: "wrap", gap: "4px 12px"}}>
    <span style={{fontWeight: 700, fontSize: "14px", letterSpacing: "0.02em"}}>Where Each ID Family Lives</span>
    <span style={{fontSize: "12px", opacity: 0.8}}>GUIDs are the keys; references bridge to league sources</span>
  </div>
  <div style={{display: "flex", flexWrap: "wrap", gap: "14px", padding: "14px 18px", background: "#FFFFFF"}}>
    <div style={{flex: "1 1 280px", border: "1px solid #C5CAE9", borderRadius: "10px", overflow: "hidden"}}>
      <div style={{padding: "8px 14px", background: "#F3F6FA", borderBottom: "1px solid #E8EAF6", fontWeight: 700, fontSize: "13px", color: "#1A237E"}}>Sportradar GUIDs <span style={{fontWeight: 400, color: "#6B7280"}}>id fields, path parameters</span></div>
      <div style={{padding: "12px 18px", display: "flex", flexWrap: "wrap", gap: "8px", alignItems: "center"}}>
        <span style={{display: "inline-block", padding: "4px 10px", borderRadius: "999px", border: "1px solid #C5CAE9", background: "#F3F6FA", color: "#1A237E", fontSize: "12px", fontWeight: 600, fontFamily: "SFMono-Regular, Menlo, Consolas, monospace", whiteSpace: "nowrap"}}>e74de5ce-3e98-4414-afe5-...</span>
        <span style={{display: "inline-block", padding: "4px 10px", borderRadius: "999px", border: "1px solid #90CAF9", background: "#E3F2FD", color: "#0D47A1", fontSize: "12px", fontWeight: 700, whiteSpace: "nowrap"}}>join on this ID</span>
      </div>
      <div style={{padding: "8px 18px", borderTop: "1px solid #E8EAF6", fontSize: "12px", color: "#6B7280"}}>The same GUID addresses the same entity in every feed and every path parameter.</div>
    </div>
    <div style={{flex: "1 1 280px", border: "1px solid #C5CAE9", borderRadius: "10px", overflow: "hidden"}}>
      <div style={{padding: "8px 14px", background: "#F3F6FA", borderBottom: "1px solid #E8EAF6", fontWeight: 700, fontSize: "13px", color: "#1A237E"}}>League references <span style={{fontWeight: 400, color: "#6B7280"}}>reference and references fields</span></div>
      <div style={{padding: "12px 18px", display: "flex", flexWrap: "wrap", gap: "8px", alignItems: "center"}}>
        <span style={{display: "inline-block", padding: "4px 10px", borderRadius: "999px", border: "1px solid #C5CAE9", background: "#F3F6FA", color: "#1A237E", fontSize: "12px", fontWeight: 600, fontFamily: "SFMono-Regular, Menlo, Consolas, monospace", whiteSpace: "nowrap"}}>reference: 1612709922</span>
        <span style={{display: "inline-block", padding: "4px 10px", borderRadius: "999px", border: "1px solid #FFCFCF", background: "#FFEBEB", color: "#B71C1C", fontSize: "12px", fontWeight: 700, whiteSpace: "nowrap"}}>not a join key</span>
      </div>
      <div style={{padding: "8px 18px", borderTop: "1px solid #E8EAF6", fontSize: "12px", color: "#6B7280"}}>Official league identifiers, stored as attributes for reconciling with league sources.</div>
    </div>
  </div>
  <div style={{padding: "8px 18px", borderTop: "1px solid #E8EAF6", fontSize: "12px", color: "#6B7280", background: "#FAFAFA"}}>Player profiles add a references array with scoped entries (NBDL, NBA, basketball sport_profile) linking the same person across leagues.</div>
</div>

<br />

***

## 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

<br />

***

## Mapping API

The [**Mapping API**](https://developer.sportradar.com/odds/reference/mapping-overview) provides on-demand, entity-level lookups that translate between Sportradar's [two ID systems](https://developer.sportradar.com/getting-started/docs/id-types) — **SR IDs** (for example, `sr:season:134469`) and **Sportradar UUIDs** — as well as select external provider ID systems. Rather than paginating through large mapping feeds, submit a supported SR ID and retrieve its mapping in a single targeted request.

Use it to link NBA G League entities to the same competitions, teams, players, and events in other Sportradar products.

Each endpoint accepts an SR ID and returns mappings to Sportradar UUIDs by default.

| Mapping Type | Endpoint                        | Input                 |
| :----------- | :------------------------------ | :-------------------- |
| Competition  | Sport Competition Mappings      | `sport_id`            |
| Competitor   | Season Competitor Mappings      | `season_id`           |
| Competitor   | Sport Event Competitor Mappings | `sport_event_id`      |
| Player       | Season Player Mappings          | `season_id`           |
| Player       | Sport Event Player Mappings     | `sport_event_id`      |
| Season       | Competition Season Mappings     | `competition_id`      |
| Sport Event  | Daily Sport Event Mappings      | `sport_id` and `date` |
| Sport Event  | Season Sport Event Mappings     | `season_id`           |
| Sport Event  | Sport Event Mappings            | `sport_event_id`      |

Season-level requests return a maximum of 100 records per page — paginate with the `start` or `offset` parameter. Cache mappings locally when your application repeatedly references the same entities.

For request samples, a full workflow, and the complete endpoint reference, see the [Mapping API overview](https://developer.sportradar.com/odds/reference/mapping-overview).

<br />

***

## 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](https://developer.sportradar.com/basketball/docs/g-league-ig-daily-change-log)) rather than by re-crawling entity feeds
* Filter the `TBD` placeholder team wherever you render team lists