Resolving IDs Across Products

This integration scenario uses the Mapping API to enrich Sportradar URNs with their IDs in other systems: look up an event, batch a season or a day, and build the local store that gives you reverse lookup.

This scenario is commonly used to:

• Enrich odds or probabilities payloads with the UUIDs used by the League Specific stat APIs
• Reconcile identifiers during integration onboarding
• Ingest a day's event mappings alongside the day's schedule
• Maintain a local ID table that can answer reverse lookups

Overview

Every lookup follows the same pattern: the URN you already hold goes in the path, and the response carries that scope's entities with their mappings. Each mapping row pairs a provider ID with the entity's ID in that provider's system (external_id); an entity can carry multiple mappings, including several from one provider.

Core API URNs → Mapping API lookup → store forward results → reverse lookup from your store

Relevant Feeds

High-Level Workflow

Integration Steps

1. Start from the URNs You Already Have

Every Sportradar Global-format payload hands you URNs: schedules give sr:sport_event: and sr:season: IDs, odds and props payloads give sr:competitor: and sr:player: IDs. No discovery calls are needed in this API; you arrive holding the ID.

2. Look Up One Event

Sport Event Mappings returns everything configured for a single event. The json and xml twins:

GET https://api.sportradar.com/mapping/trial/v2/en/sport_events/sr:sport_event:63301085/mappings.json
x-api-key: YOUR_API_KEY

{
  "generated_at": "2026-07-21T13:28:00+00:00",
  "sport_event": {
    "id": "63301085"
  }
}

<?xml version="1.0" ?>
<sport_event_mapping xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xmlns="http://schemas.sportradar.com/sportsapi/mapping/v2" generated_at="2026-07-21T13:30:24+00:00" xsi:schemaLocation="http://schemas.sportradar.com/sportsapi/mapping/v2 https://schemas.sportradar.com/sportsapi/mapping/v2/schemas/sport_event_mapping.xsd">
  <sport_event id="63301085"/>
</sport_event_mapping>

These responses come from a key with no mapping providers configured yet, so the mappings list is absent (see the note in API Basics). With providers configured, the entity carries a mappings array whose rows pair the provider's ID with the entity's external_id in that system, sorted by provider and external ID. Scoped variants return the same shape for the event's competitors and players.

3. Batch a Season or a Day

For warehouse-style loads, scope by season or date instead of calling entity by entity:

GET https://api.sportradar.com/mapping/trial/v2/en/seasons/sr:season:134469/player_mappings.json
x-api-key: YOUR_API_KEY

{
  "generated_at": "2026-07-21T13:30:27+00:00",
  "players": []
}

GET https://api.sportradar.com/mapping/trial/v2/en/sports/sr:sport:3/schedules/2026-07-21/sport_event_mappings.json
x-api-key: YOUR_API_KEY

{
  "generated_at": "2026-07-21T13:30:31+00:00",
  "sport_events": []
}

Both feeds paginate at the entity level (start, limit, and the X-Max-Results family of headers; see API Basics). The daily lookup pairs naturally with a daily schedule pull: fetch the slate, then fetch the day's mappings once.

4. Build the Local Store

Persist every mapping row you retrieve as (urn, provider, external_id). That table, indexed both ways, is your reverse lookup: when an external system hands you its ID, resolve it locally. Expect one URN to map to multiple external IDs, sometimes several within a single provider, so model the relationship as one-to-many.

5. Handle Errors

The Mapping API reports problems as JSON: a malformed URN returns 400 with the offending identifier in the message, and a well-formed but unknown ID returns 404:

{
  "generated_at": "2026-07-21T13:30:37+00:00",
  "message": "Requested identifier 'not-a-urn' is not correct"
}

{
  "generated_at": "2026-07-21T13:29:09+00:00",
  "message": "Wrong identifier"
}

Treat 400 as a bug in your request construction and 404 as an entity to skip; neither should be retried as-is.

Common Use Cases

• Odds-to-stats enrichment: step 2 (or its competitor and player variants) as events enter your system, joining odds payloads to League Specific stat feeds
• Season onboarding: step 3 once per season for players, competitors, and events, then daily deltas via the daily lookup
• Reverse resolution: step 4's local table, refreshed daily