--- updatedAt: 2026-09-29T16:30:51.000Z agentTools: siteIndex: https://developer.sportradar.com/llms.txt projectIndex: https://developer.sportradar.com/soccer/llms.txt --- # ID Handling ## Intro to IDs Our Soccer API features a number of unique identifiers. Some IDs are needed to request feeds, while others signify unique data. IDs can be attributed to competitions, seasons, competitors, players, venues, sport events (matches), referees, and many other variables.
*** ## SR IDs **SR IDs (Sportradar Identifiers)** is the ID type attributed to a variety of variables in the Soccer API. Other APIs use a combination of SR IDs and UUIDs (see below for more details). These IDs correlate to our General Sport APIs. They can have a varying structure but always begin with `sr:` and end with a number. ```xml sr_id Sample ```
*** ## UUIDs in Other Sportradar Products UUIDs follow a specific structure: `XXXXXXXX-XXXX-XXXX-XXXX-XXXXXXXXXXXX` You'll see these UUIDs in league specific APIs like the NFL API shown in the code examples below. ```xml UUID Sample ``` ```xml sr_id Sample ``` These IDs may appear as an `id` or a `sr_id` in various league-specific APIs. ```xml sr_id Sample #2 ``` ### Mappings SR IDs to UUIDs Use the [**Mapping API**](https://developer.sportradar.com/odds/reference/mapping-overview) for on-demand, entity-level lookups that translate Soccer SR IDs to external ID systems used by other Sportradar products and partners. The legacy Soccer [**Competitor Mappings**](https://developer.sportradar.com/soccer/reference/soccer-competitor-mappings) and [**Player Mappings**](https://developer.sportradar.com/soccer/reference/soccer-player-mappings) feeds remain available for bulk competitor and player mappings. See the [Mapping API](#mapping-api) section below for details.
*** ## Mapping API The [**Mapping API**](https://developer.sportradar.com/odds/reference/mapping-overview) provides on-demand, entity-level lookups that translate Soccer SR IDs (for example, `sr:season:131129`) to external ID systems used by other Sportradar products and partners. Rather than paginating through large mapping feeds, submit a supported SR ID and retrieve its mappings in a single targeted request. > ℹ️ Legacy Soccer Mapping Feeds > > The Soccer [**Competitor Mappings**](https://developer.sportradar.com/soccer/reference/soccer-competitor-mappings), [**Player Mappings**](https://developer.sportradar.com/soccer/reference/soccer-player-mappings), [**Competitor Merge Mappings**](https://developer.sportradar.com/soccer/reference/soccer-competitor-merge-mappings), and [**Player Merge Mappings**](https://developer.sportradar.com/soccer/reference/soccer-player-merge-mappings) endpoints remain available and supported. Use the Mapping API for new integrations that need on-demand lookups for specific entities; continue using the legacy feeds when you need bulk mappings or merge history.
### Soccer-Relevant Endpoints 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` |
### Sample Workflow Link Soccer entities to the IDs used by other Sportradar products or external partners. For example, retrieve partner-specific IDs for every match in a given season. 1. Retrieve a Soccer `season.id` (SR ID) from the [Seasons](https://developer.sportradar.com/soccer/reference/soccer-seasons) endpoint. For example, `sr:season:131129` (UEFA Champions League 25/26). 2. Submit the SR ID to the Season Sport Event Mappings endpoint. Results return up to 100 events per page; paginate using the `start` parameter. ```curl Initial Request curl --location 'https://api.sportradar.com/mapping/trial/v2/en/seasons/sr:season:131129/sport_event_mappings.json?start=0' \ --header 'x-api-key: [YOUR_API_KEY]' ``` ```curl Pagination curl --location 'https://api.sportradar.com/mapping/trial/v2/en/seasons/sr:season:131129/sport_event_mappings.json?start=100' \ --header 'x-api-key: [YOUR_API_KEY]' ``` 3. The response maps each Soccer SR ID (`id`) to the corresponding ID in another system (`external_id`). ```json Response Sample { "generated_at": "2026-03-27T20:00:44+00:00", "sport_events": [ { "id": "sr:match:63290531", "mappings": [ { "bookmaker_id": "sr:book:10358", "external_id": "75e97ab9-6335-4320-906a-ed279bd561cb" } ] }, { "id": "sr:match:63290533", "mappings": [ { "bookmaker_id": "sr:book:10358", "external_id": "f047c913-bdb2-455f-a4c6-fea3ae924d97" } ] } ] } ``` 4. Use the returned IDs in the downstream product or system that requires them.
### Best Practices * **Cache mappings locally** when your application repeatedly references the same entities. Storing results reduces repeat lookups, improves performance, and lessens dependence on real-time mapping calls. * **Use entity-level lookups** for known IDs instead of re-fetching full mapping feeds. Request only the IDs you need. * **Reconcile merged teams and players** using the [Competitor Merge Mappings](https://developer.sportradar.com/soccer/reference/soccer-competitor-merge-mappings) and [Player Merge Mappings](https://developer.sportradar.com/soccer/reference/soccer-player-merge-mappings) endpoints to maintain accurate historical alignment after Sportradar consolidates duplicate entities. * **Paginate season-level requests** with the `start` or `offset` parameter. Season Sport Event Mappings and similar endpoints return a maximum of 100 records per page. * **Request additional ID system mappings** by contacting the [Support Team](mailto:support@sportradar.com).
*** ## Soccer IDs in Other Sportradar Products
### Odds The [Odds APIs](https://developer.sportradar.com/odds/reference/intro) include Soccer odds data, and are based on the `sr_id` system, with IDs that look like: `sr:competitor:4792` or `sr:sport_event:51133377`. ### Access Please note that you will need access to the Odds APIs in **[your account](https://console.sportradar.com/)** to make use of these endpoints.
### Images & Editorial Our [Images](https://developer.sportradar.com/images-and-editorials/reference/images-overview) and [Editorial](https://developer.sportradar.com/images-and-editorials/reference/editorial-overview) APIs include both UUID and SR IDs within image and article entries (under `entity_id`). This allows you to sync player, team, and sport event IDs to this content. ```xml Soccer Getty Action Shot Sample (xml) <![CDATA[Manchester City FC v AFC Bournemouth - Premier League]]> Getty 2215589496 2025-05-20T00:00:00+00:00 <![CDATA[Crystal Palace FC v Wolverhampton Wanderers FC - Premier League]]> Getty 2215592982 2025-05-20T00:00:00+00:00 <![CDATA[Manchester City FC v AFC Bournemouth - Premier League]]> Getty 2215584119 2025-05-20T00:00:00+00:00 ``` ```xml Soccer Premium Editorial Sample (xml) <![CDATA[Britain Soccer Premier League]]> <![CDATA[Britain Soccer Premier League]]> <![CDATA[Britain Soccer Premier League]]> ```
### Widgets Our [Soccer Widgets](https://developer.sportradar.com/widgets/docs/soccer-getting-started) often will require the input of a unique match, team, player, or season ID.
*** ## Event (Match) IDs Each Soccer match will have its own unique identifier under `sport_event_id`. See below for a sample taken from the [Daily Schedules](https://developer.sportradar.com/soccer/reference/soccer-daily-schedules) endpoint. ```xml ``` ```json JSON { "sport_event": { "id": "sr:sport_event:57380311", "start_time": "2025-06-01T00:00:00+00:00", "start_time_confirmed": true, "sport_event_context": { "sport": { "id": "sr:sport:1", "name": "Soccer" }, "category": { "id": "sr:category:49", "name": "Chile", "country_code": "CHL" }, "competition": { "id": "sr:competition:27665", "name": "Primera Division", "parent_id": "sr:competition:244", "gender": "men" }, "season": { "id": "sr:season:127935", "name": "Primera Division 2025", "start_date": "2025-02-15", "end_date": "2025-12-07", "year": "2025", "competition_id": "sr:competition:27665" }, "stage": { "order": 1, "type": "league", "phase": "regular season", "start_date": "2025-02-15", "end_date": "2025-12-07", "year": "2025" }, "round": { "number": 13 }, "groups": [ { "id": "sr:league:90581", "name": "Primera Division 2025" } ] } } } ``` Once created, match IDs are unchanging, except in the rare case that a match is [postponed](https://developer.sportradar.com/soccer/docs/soccer-ig-match-status-workflow#postponed), or a match is mistakenly created twice (the duplicated UUID would be removed). ### Event ID Updates The following endpoints are useful for tracking changes to `sport_event_id` values over time: * Use the [Sport Events Created](https://developer.sportradar.com/soccer/reference/soccer-sport-events-created) endpoint to identify new `sport_event_id`s generated in the past 24 hours. * Use the [Sport Events Removed](https://developer.sportradar.com/soccer/reference/soccer-sport-events-removed) endpoint to detect and remove duplicate or invalid events. * Use the [Sport Events Updated](https://developer.sportradar.com/soccer/reference/soccer-sport-events-updated) endpoint to monitor matches that have been updated in the past 24 hours.
*** ## Competitor (Team) IDs Each soccer team has a unique identifier available in the `competitor.id` field. To retrieve all active teams for a given season of a competition, use the [Season Competitors](https://developer.sportradar.com/soccer/reference/soccer-season-competitors) endpoint. ```xml Season Competitors (XML) ``` ```json Season Competitors (JSON) { "season_competitors": [ { "id": "sr:competitor:3", "name": "Wolverhampton Wanderers", "short_name": "Wolverhampton", "abbreviation": "WOL", "gender": "male" }, { "id": "sr:competitor:7", "name": "Crystal Palace", "short_name": "Crystal Palace", "abbreviation": "CRY", "gender": "male" }, { "id": "sr:competitor:14", "name": "Nottingham Forest", "short_name": "Nottingham", "abbreviation": "NFO", "gender": "male" }, { "id": "sr:competitor:17", "name": "Manchester City", "short_name": "Manchester City", "abbreviation": "MCI", "gender": "male" }, { "id": "sr:competitor:30", "name": "Brighton & Hove Albion", "short_name": "Brighton", "abbreviation": "BRI", "gender": "male" }, { "id": "sr:competitor:31", "name": "Leicester City", "short_name": "Leicester", "abbreviation": "LEI", "gender": "male" }, { "id": "sr:competitor:32", "name": "Ipswich Town", "short_name": "Ipswich", "abbreviation": "IPS", "gender": "male" }, { "id": "sr:competitor:33", "name": "Tottenham Hotspur", "short_name": "Tottenham", "abbreviation": "TOT", "gender": "male" }, { "id": "sr:competitor:35", "name": "Manchester United", "short_name": "Manchester United", "abbreviation": "MUN", "gender": "male" }, { "id": "sr:competitor:37", "name": "West Ham United", "short_name": "West Ham", "abbreviation": "WHU", "gender": "male" }, { "id": "sr:competitor:38", "name": "Chelsea FC", "short_name": "Chelsea", "abbreviation": "CHE", "gender": "male" }, { "id": "sr:competitor:39", "name": "Newcastle United", "short_name": "Newcastle", "abbreviation": "NEW", "gender": "male" }, { "id": "sr:competitor:40", "name": "Aston Villa", "short_name": "Aston Villa", "abbreviation": "AVL", "gender": "male" }, { "id": "sr:competitor:42", "name": "Arsenal FC", "short_name": "Arsenal", "abbreviation": "ARS", "gender": "male" }, { "id": "sr:competitor:43", "name": "Fulham FC", "short_name": "Fulham", "abbreviation": "FUL", "gender": "male" }, { "id": "sr:competitor:44", "name": "Liverpool FC", "short_name": "Liverpool", "abbreviation": "LFC", "gender": "male" }, { "id": "sr:competitor:45", "name": "Southampton FC", "short_name": "Southampton", "abbreviation": "SOU", "gender": "male" }, { "id": "sr:competitor:48", "name": "Everton FC", "short_name": "Everton", "abbreviation": "EVE", "gender": "male" }, { "id": "sr:competitor:50", "name": "Brentford FC", "short_name": "Brentford", "abbreviation": "BRE", "gender": "male" }, { "id": "sr:competitor:60", "name": "AFC Bournemouth", "short_name": "Bournemouth", "abbreviation": "BOU", "gender": "male" } ] } ``` ### Competitor Merges Use the [**Competitor Merge Mappings**](https://developer.sportradar.com/soccer/reference/soccer-competitor-merge-mappings) endpoint to identify teams that have merged. This allows you to map old competitor IDs to a new, unified team ID and maintain accurate historical data alignment.
### TBD Teams The `competitor.id` may occasionally represent a placeholder team labeled as TBD when the matchup is not yet determined. This unique ID allows match information to be included even when the participating team is still unknown. ``
*** ## Player IDs Each Soccer player will have their own unique identifier under `player.id`. You can locate all players on a given team in the [Competitor Profile](https://developer.sportradar.com/soccer/reference/soccer-competitor-profile) endpoint, and retrieve detailed player biographical info and stats in the [Player Profile](https://developer.sportradar.com/soccer/reference/soccer-player-profile) endpoint. Player IDs will not change once created. ```xml Team Roster Sample (xml) ``` ```json Player Profile Sample (json) { "player": { "id": "sr:player:159665", "name": "Salah, Mohamed", "type": "forward", "date_of_birth": "1992-06-15", "nationality": "Egypt", "country_code": "EGY", "height": 175, "weight": 71, "jersey_number": 11, "preferred_foot": "left", "place_of_birth": "Basyoun, El Gharbia", "gender": "male" }, "competitors": [ { "id": "sr:competitor:4758", "name": "Egypt", "country": "Egypt", "country_code": "EGY", "abbreviation": "EGY", "gender": "male" }, { "id": "sr:competitor:44", "name": "Liverpool FC", "country": "England", "country_code": "ENG", "abbreviation": "LFC", "gender": "male" } ], "roles": [ { "type": "player", "active": true, "competitor": { "id": "sr:competitor:4758", "name": "Egypt", "country": "Egypt", "country_code": "EGY", "abbreviation": "EGY", "gender": "male" }, "jersey_number": 10 }, { "type": "player", "active": false, "competitor": { "id": "sr:competitor:22679", "name": "Egypt", "country": "Egypt", "country_code": "EGY", "abbreviation": "EGY", "gender": "male", "age_group": "U20" }, "jersey_number": 12 }, { "type": "player", "active": false, "competitor": { "id": "sr:competitor:69224", "name": "Egypt", "country": "Egypt", "country_code": "EGY", "abbreviation": "EGY", "gender": "male", "age_group": "U23" }, "jersey_number": 11 }, { "type": "player", "active": false, "competitor": { "id": "sr:competitor:42365", "name": "Al Mokawloon Al Arab", "country": "Egypt", "country_code": "EGY", "abbreviation": "MOK", "gender": "male" }, "start_date": "2008-07-01 00:00:00", "end_date": "2012-06-30 00:00:00" }, { "type": "player", "active": false, "competitor": { "id": "sr:competitor:2501", "name": "FC Basel 1893", "country": "Switzerland", "country_code": "CHE", "abbreviation": "FCB", "gender": "male" }, "start_date": "2012-07-01 00:00:00", "end_date": "2014-01-25 00:00:00", "jersey_number": 22 }, { "type": "player", "active": false, "competitor": { "id": "sr:competitor:38", "name": "Chelsea FC", "country": "England", "country_code": "ENG", "abbreviation": "CHE", "gender": "male" }, "start_date": "2014-01-26 00:00:00", "end_date": "2016-06-30 00:00:00", "jersey_number": 17 }, { "type": "on_loan", "active": false, "competitor": { "id": "sr:competitor:2693", "name": "ACF Fiorentina", "country": "Italy", "country_code": "ITA", "abbreviation": "FIO", "gender": "male" }, "start_date": "2015-02-02 00:00:00", "end_date": "2015-06-30 00:00:00", "jersey_number": 74 }, { "type": "on_loan", "active": false, "competitor": { "id": "sr:competitor:2702", "name": "AS Roma", "country": "Italy", "country_code": "ITA", "abbreviation": "ROM", "gender": "male" }, "start_date": "2015-08-06 00:00:00", "end_date": "2016-06-30 00:00:00", "jersey_number": 11 }, { "type": "player", "active": false, "competitor": { "id": "sr:competitor:2702", "name": "AS Roma", "country": "Italy", "country_code": "ITA", "abbreviation": "ROM", "gender": "male" }, "start_date": "2016-07-01 00:00:00", "end_date": "2017-06-30 00:00:00", "jersey_number": 11 }, { "type": "player", "active": true, "competitor": { "id": "sr:competitor:44", "name": "Liverpool FC", "country": "England", "country_code": "ENG", "abbreviation": "LFC", "gender": "male" }, "start_date": "2017-07-01 00:00:00", "jersey_number": 11 } ] } ``` ### Player Merges Use the [**Player Merge Mappings**](https://developer.sportradar.com/soccer/reference/soccer-player-merge-mappings) endpoint to track players whose profiles have been merged. This helps ensure continuity when a player’s data has been consolidated under a new player ID. ### Access all Player IDs Iterate through the past [Seasonal Players](https://developer.sportradar.com/soccer/reference/soccer-season-players) feeds for each season and team to obtain all player IDs in the Soccer API. Alternately, request the [Sport Event Lineups](https://developer.sportradar.com/soccer/reference/soccer-sport-event-lineups) endpoint for every Soccer match to capture every player who has appeared on a team roster.
*** ## Season IDs Each Soccer season will have its own unique identifier under `season.id`. You can locate all historical seasons in the [Seasons](https://developer.sportradar.com/soccer/reference/soccer-seasons) feed. Season IDs will not change once created. ```xml Seasons Sample (xml) ``` ```json Seasons Sample (json) { "seasons": [ { "id": "sr:season:92261", "name": "UEFA Euro 2024", "start_date": "2024-06-14", "end_date": "2024-07-14", "year": "2024", "competition_id": "sr:competition:1" }, { "id": "sr:season:58428", "name": "UEFA Euro 2020", "start_date": "2021-06-11", "end_date": "2021-07-11", "year": "2021", "competition_id": "sr:competition:1" }, { "id": "sr:season:12170", "name": "UEFA Euro 2016", "start_date": "2016-06-10", "end_date": "2016-07-11", "year": "2016", "competition_id": "sr:competition:1" }, { "id": "sr:season:131129", "name": "UEFA Champions League 25/26", "start_date": "2025-07-08", "end_date": "2026-05-31", "year": "25/26", "competition_id": "sr:competition:7" }, { "id": "sr:season:119239", "name": "UEFA Champions League 24/25", "start_date": "2024-07-09", "end_date": "2025-05-31", "year": "24/25", "competition_id": "sr:competition:7" }, { "id": "sr:season:106479", "name": "UEFA Champions League 23/24", "start_date": "2023-06-27", "end_date": "2024-06-01", "year": "23/24", "competition_id": "sr:competition:7" } ] } ```
*** ## Venue IDs Each soccer venue will have its own unique identifier under `venue.id`. You can locate a team's home venue in the [Competitor Profile](https://developer.sportradar.com/soccer/reference/soccer-competitor-profile), and each Sport Event feed will include the venue ID for that matchup. Venue IDs will not change once created. ```xml Venu Sample (xml) ``` ```json Venue Sample (json) { "competitor": { "id": "sr:competitor:44", "name": "Liverpool FC", "short_name": "Liverpool", "country": "England", "country_code": "ENG", "abbreviation": "LFC", "gender": "male" }, "category": { "id": "sr:category:1", "name": "England", "country_code": "ENG" }, "sport": { "id": "sr:sport:1", "name": "Soccer" }, "jerseys": [ { "type": "home", "base": "e41e2c", "sleeve": "e41e2c", "number": "ffffff", "squares": false, "stripes": false, "horizontal_stripes": false, "split": false, "shirt_type": "short_sleeves", "sleeve_detail": "f20202" }, { "type": "away", "base": "000000", "sleeve": "4fb5c1", "number": "ffffff", "squares": false, "stripes": false, "horizontal_stripes": false, "split": false, "shirt_type": "short_sleeves" }, { "type": "goalkeeper", "base": "18fffb", "sleeve": "121820", "number": "f3f5f0", "squares": false, "stripes": false, "horizontal_stripes": false, "split": false, "shirt_type": "short_sleeves" }, { "type": "third", "base": "ffffff", "sleeve": "de020e", "number": "000000", "squares": false, "stripes": false, "horizontal_stripes": false, "split": false, "shirt_type": "short_sleeves" } ], "manager": { "id": "sr:player:2250", "name": "Slot, Arne", "date_of_birth": "1978-09-17", "nationality": "Netherlands", "country_code": "NLD", "preferred_foot": "right", "gender": "male" }, "venue": { "id": "sr:venue:579", "name": "Anfield", "capacity": 61276, "city_name": "Liverpool", "country_name": "England", "map_coordinates": "53.430622,-2.960919", "country_code": "ENG", "timezone": "Europe/London" } } ``` **Note:** [Sportradar IDs](https://developer.sportradar.com/getting-started/docs/id-types#sr-ids) will be consistent across sports and leagues, where available. Meaning those venue IDs would be consistent across APIs.