ID Handling

This guide explains how identifiers work in the Global Baseball API: which IDs are primary, how they relate across feeds and packages, and how Global Baseball IDs connect to other Sportradar products. Getting the ID model right is the foundation of a stable integration.

sr: URNs Are the Primary Identifiers

Every entity is identified by a Sportradar URN of the form sr:{type}:{number}: competitions, seasons, sport events, competitors, players, venues, standings groups, and cup rounds. The full family table, with an example of each, is in Fundamentals. These URNs are consistent across every Global Baseball feed and are the values you should store and reuse as primary keys.

Three properties make them dependable:

• Stable across feeds: the sport event ID from a schedule works in the summary, timeline, lineups, and probability feeds without translation.
• Stable across the packages: the core API and the Probabilities package share one ID space; sr:season:134469 (MLB 2026) keys season summaries, standings, and outright probabilities alike.
• Stable across Sportradar's General Sport catalog: the same URNs identify these entities in Sportradar's odds and probabilities products, so sr:competition:109 means MLB everywhere the sr: scheme appears.

The GUID Bridge to the MLB API

Sportradar's MLB API identifies entities with GUIDs, and its feeds also carry the matching URN as sr_id on games, teams, venues, players, and seasons. For a bulk crosswalk, the mapping feeds pair the two, one row per entity, with the URN in id and the MLB API GUID in external_id:

Competitor Mappings and Player Mappings both page at up to 1,000 rows. Three rows of each:

GET https://api.sportradar.com/baseball/trial/v2/en/competitors/mappings.json
x-api-key: YOUR_API_KEY

{
  "generated_at": "2026-07-21T17:52:51+00:00",
  "mappings": [
    {
      "external_id": "4c61669c-148d-44be-b71e-ddeab97278e1",
      "id": "sr:competitor:981175"
    },
    {
      "external_id": "f5614d2a-9974-4c07-816b-42f7a6941fab",
      "id": "sr:competitor:981173"
    },
    {
      "external_id": "035c8443-d4c5-46c3-98e3-e6d352ebe605",
      "id": "sr:competitor:981171"
    }
  ]
}

{
  "generated_at": "2026-07-21T17:52:53+00:00",
  "mappings": [
    {
      "external_id": "e0604f63-87ec-4502-b69e-c7f75acf960c",
      "id": "sr:player:3225736"
    },
    {
      "external_id": "fb382d03-8623-4981-8925-454f643d5532",
      "id": "sr:player:3225746"
    },
    {
      "external_id": "d9d468ba-93dc-4584-928c-01f2bdf6ba0e",
      "id": "sr:player:3225740"
    }
  ]
}

When IDs Change

Two mechanisms cover the rare cases where an identifier is retired:

• Merges: when duplicate records are found and combined, Competitor Merge Mappings and Player Merge Mappings list the merged ID alongside the retained ID to keep. Entries are retained for one week, so the lists are empty whenever no merge has occurred recently.

Apply both on a regular cadence so retired IDs never linger as primary keys; see Monitoring Data Changes.

Choosing Storage Keys

• Games: the sport event URN is the primary key.
• Standings rows: the same team appears in its division, league, and overall groups, so key rows on the pair of group id (sr:league:) and competitor id; see Tracking Standings.
• Brackets: cup rounds carry sr:cup_round: IDs whose linked_cup_rounds wire the bracket together; store the round ID and resolve games through each round's sport_events.
• Players: the player URN is stable across teams and seasons; the current team comes from Player Profile, not from the ID.

Best Practices

• Store and reuse sr: URNs as primary keys for all Global Baseball data
• If you also consume the MLB API, store the GUID alongside the URN once, from the MLB feed's sr_id or the mapping feeds' external_id, and join locally
• Poll the merge mapping feeds and Sport Events Removed on a slow cadence and retire IDs they name
• Never parse meaning out of the numeric part of a URN; treat the whole string as opaque