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 Mappings
Looking 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 Links

Postman Workspace

Our entire Media APIs are available on Postman. Click the link above to be taken directly to our Mapping API collection.

Feel free to follow and/or fork any collections to receive updates.

Schema Download

Open the zip file below to access our Mapping API XSD schema.

Mapping v2 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.