Get started with Sportradar's Mapping API
Introduction
Sportradar’s Mapping API allows you to translate between Sportradar’s two ID systems, including SR IDs (for example, sr:season:xxxx) and Sportradar UUIDs (for example, xxxxxxx-xxxxxxxx-xxxxxxxxxx). It can also support mappings to select external provider IDs.
Rather than consuming large, paginated mapping feeds, the Mapping API provides targeted, entity-level lookups. Submit a supported ID and retrieve its corresponding ID in another supported system. This streamlined approach makes it easier to connect data across Sportradar products and simplify ID reconciliation in your workflows.
Additional MappingsLooking for additional ID mappings beyond SR IDs -> Sportradar UUIDs? Reach out to our Support Team!
Use Case Workflow
The Mapping API is especially useful when integrating multiple Sportradar products that rely on different ID systems.
For example, the MLB API returns Sportradar UUIDs (xxxxxxx-xxxxxxxx-xxxxxxxxxx), while the Odds Comparison APIs reference the same entities using Sportradar IDs (sr:season:xxxx). The Mapping API allows you to translate between those IDs and link the same entity across both products.
Goal
Link all 2026 MLB games using the SR IDs returned by the Odds Comparison API into the corresponding Sportradar UUIDs required by the MLB API.
Steps
⚾ **Step 1: Retrieve season ID from the Global Baseball API**
Use the Global Baseball Seasons endpoint to retrieve the 2026 MLB season ID. Alternatively, use any Odds Comparison API endpoint to retrieve any other game, season, team, or player you want to link.
The Seasons endpoint will include:
{
"id": "sr:season:134469",
"name": "MLB 2026",
"start_date": "2026-03-25",
"end_date": "2026-11-01",
"year": "2026",
"competition_id": "sr:competition:109"
},🔗 **Step 2: Call the Mapping API**
Submit the SR ID (sr:season:134469) to the appropriate Mapping API endpoint (in this case, Season Sport Event Mappings) for an SR ID → Sportradar UUID lookup.
This endpoint returns a maximum of 100 games. Paginate through the remaining results using start or offset to receive the entire payload.
curl --location 'https://api.sportradar.com/mapping/trial/v2/en/seasons/sr:season:134469/sport_event_mappings.json?start=0' \
--header 'x-api-key: [YOUR_API_KEY]'curl --location 'https://api.sportradar.com/mapping/trial/v2/en/seasons/sr:season:134469/sport_event_mappings.json?start=100' \
--header 'x-api-key: [YOUR_API_KEY]'🔑 **Step 3: Retrieve the mapped Sportradar UUIDs**
The Mapping API response returns the sport events mapped from the SR IDs to the Sportradar UUIDs
- ex.
"id": "sr:match:63290531"="external_id": "75e97ab9-6335-4320-906a-ed279bd561cb"
{
"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"
}
]
},
{
"id": "sr:match:63290535",
"mappings": [
{
"bookmaker_id": "sr:book:10358",
"external_id": "8cdeccb6-2fe5-4c0f-9b01-c288e7e61e82"
}
]
},
{
"id": "sr:match:63290537",
"mappings": [
{
"bookmaker_id": "sr:book:10358",
"external_id": "02602d5f-362c-4049-a1e8-7331a27a9198"
}
]
},
{
"id": "sr:match:63290539",
"mappings": [
{
"bookmaker_id": "sr:book:10358",
"external_id": "4b03123a-1411-4442-9932-35e12f8c236f"
}
]
},🔄 **Step 4: Use the mapped UUIDs in the MLB API**
Use the returned Sportradar UUID in the appropriate MLB API endpoint.
This allows you to:
- Match the same games across both APIs
- Connect Odds Comparison API entities to MLB API data
- Normalize entities inside your own application or database
- Reconcile the same teams, players, games, or seasons across products
💾 **Step 5: Cache mappings when possible**
If your application repeatedly references the same entities, store mappings locally to:
- Reduce repeated lookup requests
- Improve performance
- Simplify downstream joins across products
- Reduce dependency on repeated real-time mapping calls
Endpoint Descriptions
See below for mapping endpoint groupings. Each endpoint takes in a SR ID and returns mappings for a configured ID system, Sportradar UUIDs by default.
Competition Mapping
Sport Competition Mappings — Get competition mappings for a given sport_id.
Competitor Mapping
Season Competitor Mappings — Get competitor mappings for a given season_id.
Sport Event Competitor Mappings — Get competitor mappings for a given sport_event_id.
Player Mapping
Season Player Mappings — Get player mappings for a given season_id.
Sport Event Player Mappings — Get player mappings for a given sport_event_id.
Season Mapping
Competition Season Mappings — Get season mappings for a given competition_id.
Sport Event Mapping
Daily Sport Event Mappings — Get sport event mappings for a given sport_id and date.
Season Sport Event Mappings — Get sport event mappings for a given season_id.
Sport Event Mappings — Get sport event mappings for a given sport_event_id.
Data Points Summary
A quick overview of all data points available through the Mapping v2 API.
Events
| Sport Event Id Competition Id | Competitor Id Player Id | Season Id |
Mapping IDs
| Bookmaker Id (Mapping Entity Id) | External Id |
Integration Resources
Postman Workspace
Run in PostmanOur full Media API suite—including the Mapping collection—lives in our public Postman workspace. Fork or follow any collection to get updates automatically.
Schema Download
Open the zip file below to access our Mapping API XSD schema.
MCP Server
The Sportradar Mapping MCP Server is a Model Context Protocol (MCP) implementation that bridges AI assistants directly to our Mapping API feeds. It allows LLMs to use standardized tools to fetch our sports data, helping to power your applications, assist in coding, and streamlining your integration.
For detailed instructions on how to set up and use this integration, visit our MCP Server documentation.