ID Types

Every entity in Sportradar APIs — leagues, teams, players, venues, games, plays, and more — carries unique identifiers. This page explains the ID systems you'll encounter, which APIs use which, and how to translate between them.

Which ID System Does My API Use?

There are two primary ID systems:

Many payloads include both — a League Specific team record may carry a UUID as id and an SR ID as sr_id. To translate between systems programmatically, use the Mapping API.

Primary IDs

UUIDs

UUIDs (Universally Unique Identifiers) follow the structure XXXXXXXX-XXXX-XXXX-XXXX-XXXXXXXXXXXX:

<team id="c5a59daa-53a7-4de0-851f-fb12be893e9e" name="Lions" market="Detroit" alias="DET" reference="4985" sr_id="sr:competitor:4419"></team>

These UUIDs may appear as an id or a us_id in various APIs, or both values may be present.

<mapping us_id="c5a59daa-53a7-4de0-851f-fb12be893e9e" id="sr:competitor:4419"></mapping>

SR IDs

SR IDs (Sportradar Identifiers) vary in structure but always begin with sr: and end with a number:

<competitor id="sr:competitor:4419" name="Detroit Lions" country="USA" country_code="USA" abbreviation="DET"/>

These IDs may appear as an id or an sr_id in various APIs.

IDs Across APIs and Products

IDs do not automatically transfer between Sportradar products — the same real-world entity can carry different identifiers in different APIs:

• A venue shared by the NBA and NBA G League may have distinct UUIDs and/or SR IDs in each API.
• A player moving from college to pro carries a new ID in the professional league's API (with a source_id linking back — below).
• A game referenced by both the MLB API (UUID) and Odds Comparison APIs (SR ID) requires translation to connect.

The Mapping API is the tool for reconciling all of these. Submit a supported SR ID to retrieve the corresponding Sportradar UUID — without consuming large paginated feeds. The lookup runs in one direction only: SR ID → Sportradar UUID. Supported entity types:

• Competitions — by sport_id
• Competitors — by season_id or sport_event_id
• Players — by season_id or sport_event_id
• Seasons — by competition_id
• Sport Events — by sport_id and date, season_id, or sport_event_id

Each Integration Guide also includes an ID Types section covering that league's specifics.

Other IDs

Source IDs

An ID from another Sportradar API, included to link entities across leagues — such as a player drafted from NCAA to the NFL:

<player id="acc141bf-531f-4576-8ac4-3f91c850293e" source_id="e9d4ab78-3572-47ab-b4d3-e04c5af231f3" first_name="Martavis" last_name="Bryant" sr_id="sr:player:829235" position="WR"/>

Entity IDs

Entity IDs appear only in our Images and Editorial Content APIs, accompanied by an origin attribute describing the ID system they belong to:

<ref name="Guentzel, Jake" type="profile" sport="nhl" sportradar_id="1130edda-c071-4ae6-9de5-1e35525c72bd" primary="true">
  <entity_id origin="SR" id="sr:player:976717" sport="nhl"/>
  <entity_id origin="SD" id="1130edda-c071-4ae6-9de5-1e35525c72bd" sport="nhl"/>
  <entity_id origin="NHL" id="8477404" sport="nhl"/>
</ref>

League/Partner Reference IDs

League Specific APIs may include a reference attribute carrying the league's own identifier (visible in the UUID sample above). Use these to align with league-published data where needed.

Country Codes

All Sportradar APIs adhere to the ISO 3166-1 alpha-3 standard for country codes, unless otherwise specified — a three-letter country_code value (USA, GBR, DEU).

{
    "id": "sr:player:991181",
    "name": "Haaland, Erling",
    "type": "forward",
    "date_of_birth": "2000-07-21",
    "nationality": "Norway",
    "country_code": "NOR",
},

Note that country_code is a standardized format value, not a Sportradar-issued identifier. Use it for interoperable country references; use SR IDs or UUIDs to identify entities.

Things to Know

• Role-based ID fields: The same entity ID appears under different attribute names by context — a team ID as home – id, away – id, or winner_id; a player ID as scorer – id or assist – id. They all reference the same underlying entity.
• Accessing previous seasons (Tournament-based APIs): Tournament IDs and Season IDs are interchangeable when calling Tournament endpoints. Interrogate the Tournament Seasons endpoint for the required Season ID, then use it to call any Tournament endpoint.
• Accessing previous seasons (Competition-based APIs): Use the Competitions List endpoint to find your Competition ID → call Competition Seasons to locate the Season ID → use that Season ID with any Season endpoint.