ID Types

Within Sportradar APIs you will encounter many different ID values. IDs can be attributed to leagues, conferences, divisions, franchises, teams, venues, drafts, weeks, periods, quarters, coaches, managers, prospects, draft picks, trades, transactions, drives, possessions, plays, in-game events, and many other variables. To translate IDs between Sportradar's ID systems or link them to external provider IDs, use the Mapping API.

Primary IDs

There are two primary types of ID that can be attributed to a variety of variables: UUIDs (Universally Unique Identifiers) and SR IDs (Sportradar Identifiers). They are used as a way to directly identify the given variable within the API, across multiple Sportradar APIs, or within data outside of Sportradar. The forms of IDs that you will encounter within Sportradar products, are detailed below:

UUID IDs

UUID IDs follow a specific 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

These IDs can have a varying structure but always begin with sr: and end with a number.

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

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

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

👍

Note:

The sr_id is an optional value in the League Specific APIs and it's strongly encouraged to utilize the UUIDs as your primary key.

🔗

Tip:

To translate between UUID IDs and SR IDs programmatically, use the Mapping API. Submit a supported SR ID to retrieve its corresponding Sportradar UUID, or vice versa — without consuming large paginated feeds.

Other IDs

Source IDs

ID from another Sportradar API, such as a player from NCAA being drafted to the NFL. We include the source_id from the NCAA API so player information can be linked.

<code><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"/></code>

Entity IDs

Entity IDs are normally accompanied by an origin attribute that describes where the ID is linked to. For instance, image data may have an ID for a given player, we include that ID as a reference to our other APIs. Entity IDs only appear in our Images and Editorial Content APIs.

<code><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></code>

Mapping API

When integrating multiple Sportradar products that rely on different ID systems, use the Mapping API to perform entity-level ID lookups. The Mapping API translates between SR IDs and Sportradar UUIDs, and can also support mappings to select external provider IDs.

For example, if the MLB API returns a Sportradar UUID and the Odds Comparison API references the same game using an SR ID, the Mapping API allows you to link those two identifiers without consuming large paginated feeds.

The following entity types are supported:

• 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

🙋

Note:

Need mappings beyond SR IDs → Sportradar UUIDs? Contact the Support Team.

Notes Regarding IDs

Some IDs are displayed in different ways in different places along logical lines. For instance, some endpoints display a team – id to reference the teams that are competing in a specific sport event, but the team id may also be used to reflect a home team home – id, away team away – id, or an event winner sport_event_status - winner_id.

Another instance of this occurs frequently with player – id referencing the player, but the ID may also appear in event information to reflect player as a goal scorer scorer – id, or as providing an assist assist – id.

With various forms of IDs in the Sportradar APIs, some duplication can occur. For instance, a venue that is used by both the NBA and NBA G League may have multiple venue UUID IDs and/or SR IDs. Similarly, a college player may have a UUID ID and/or SR ID that is different if they have joined a professional league. Use the Mapping API to reconcile IDs for the same entity across different Sportradar products.

Tournament IDs and Season IDs are interchangeable when calling Tournament endpoints. This is done so you are able to access a previous season's data. To do this:

1. Interrogate the Tournaments Seasons endpoint to ascertain the required Season ID.
2. Use that Season ID to call any of the Tournament endpoints.

To access a previous season's data in an API where Competition IDs are used:

1. Interrogate the Competitions List endpoint to ascertain the required Competition ID.
2. Use that Competition ID to call the Competition Seasons endpoint and locate your desired Season ID.
3. Use that Season ID to call any of the Season endpoints.