Mapping Overview

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.

📘
New to the Mapping API?
Check out our Mapping API Integration Guide for common workflows, feed dependencies, and best practices to get up and running.

🙋
Additional Mappings
Looking for additional ID mappings beyond SR IDs -> Sportradar UUIDs? Reach out to our Support Team!

API Map

To best utilize the Mapping API, you will need specific parameters to create your API calls. The map below shows every feed in the API, grouped by the entity being mapped; the key marks the identifier each feed takes, and each entry links out to its endpoint page.

Each feed takes the URN of a parent entity (a sport, competition, season, or sport event) and returns ID pairs linking Sportradar URNs to League-Specific API IDs.

Use Case Workflow

The Mapping API resolves an ID you already hold into the matching ID in another Sportradar system. It is most useful when an entity reaches you as an SR ID — from the Odds Comparison APIs, a Global API, or a Probabilities feed — and you need the Sportradar UUID to call a League Specific API, but have no League Specific payload in hand to read it from.

💡
Check whether you need a lookup at all
Several League Specific APIs now return sr_id alongside the UUID on games, teams, venues, players, and seasons — including the MLB API. If you are already pulling the League Specific feed, read both identifiers straight from that response and store them together. No mapping call is needed.
Reach for the Mapping API when you have only the SR ID, which is the case this workflow covers.

Goal

Starting from a single SR ID delivered by an Odds Comparison feed, resolve the sport event — and the teams and players on it — into the Sportradar UUIDs needed to call MLB API game feeds.

Steps

🎲 **Step 1: Start from the SR ID you already have**

An Odds Comparison, Probabilities, or Global API payload identifies the event by its SR ID. No additional call is needed to obtain it — it is already in the response you are consuming.

{
    "sport_event": {
        "id": "sr:match:63290531",
        "start_time": "2026-03-27T20:00:00+00:00",
        "competitors": [
            { "id": "sr:competitor:3636", "name": "San Diego Padres", "qualifier": "home" },
            { "id": "sr:competitor:3634", "name": "San Francisco Giants", "qualifier": "away" }
        ]
    }
}

At this point you cannot read the MLB sr_id shortcut: that field lives inside the MLB record, and reaching the MLB record requires the UUID you do not yet have. That circular dependency is what the Mapping API breaks.

🔗 **Step 2: Resolve the event with Sport Event Mappings**

Submit the single SR ID to Sport Event Mappings for a targeted SR ID → Sportradar UUID lookup. Unlike the season-level feed, this returns one event and needs no pagination.

curl --location 'https://api.sportradar.com/mapping/trial/v2/en/sport_events/sr:match:63290531/mappings.json' \
--header 'x-api-key: [YOUR_API_KEY]'

The external_id is the MLB API UUID for that game.

{
    "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"
                }
            ]
        }
    ]
}

👥 **Step 3: Resolve the teams and players on that event**

The event mapping gives you the game. To resolve the participants on it, call the two companion endpoints with the same SR ID:

Sport Event Competitor Mappings — team UUIDs
Sport Event Player Mappings — player UUIDs

curl --location 'https://api.sportradar.com/mapping/trial/v2/en/sport_events/sr:match:63290531/competitor_mappings.json' \
--header 'x-api-key: [YOUR_API_KEY]'

curl --location 'https://api.sportradar.com/mapping/trial/v2/en/sport_events/sr:match:63290531/player_mappings.json' \
--header 'x-api-key: [YOUR_API_KEY]'

If you need the same resolution for a whole season rather than one event, use the season-level equivalents — Season Competitor Mappings and Season Player Mappings — which are paginated at 100 results per page.

🔄 **Step 4: Call the MLB API with the mapped UUID**

Place the external_id in the appropriate MLB API path. The game is now addressable in both systems.

curl --location 'https://api.sportradar.com/mlb/trial/v8/en/games/75e97ab9-6335-4320-906a-ed279bd561cb/summary.json' \
--header 'x-api-key: [YOUR_API_KEY]'

The MLB response carries sr_id on the game, teams, venue, and players — the same identifiers you started from. Read them back and you have a verified pair for every entity on the event, not just the game.

💾 **Step 5: Store the pairs and stop looking them up**

Persist each sr_id ↔ UUID pair the first time you resolve it. Because the League Specific response returns both identifiers, every MLB call you make afterwards extends that index for free.

Resolve an entity once, then read from your own store
Build the index in bulk by pulling a schedule feed, which carries sr_id on every game, team, and venue it returns
Fall back to the Mapping API only for entities you have not seen before
Re-check mappings for entities that can change over a season, such as player team assignments

Over time this reduces the Mapping API to what it is best at: resolving the entity you have never seen, on demand.

When the Mapping API is still required

Situation	Why
You hold only an SR ID and no League Specific record	The `sr_id` field cannot be read without the UUID that retrieves the record
The League Specific API for that sport does not return `sr_id`	Not every League Specific API carries the crosswalk yet
You need a mapping to a non-Sportradar provider ID system	Mappings beyond SR ID → UUID are configured per account; contact Support

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

Integration Guide

Set up an account, learn the Mapping API basics, study the ID resolution workflow, and more by visiting our Mapping API Integration Guide!

Postman Workspace

🚀
Run in Postman
Our 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.

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.