API Basics

This page covers the practical basics of the Mapping API: authentication, the URL shape, the endpoint catalog, pagination, and its error behavior (which differs from the Odds Comparison APIs in a useful way: errors are JSON).

Authentication

Every request is authenticated with your API key in the x-api-key header:

GET https://api.sportradar.com/mapping/trial/v2/en/sports/sr:sport:3/competition_mappings.json
x-api-key: YOUR_API_KEY

Keep the key server-side; do not embed it in client applications.

Base URL and URL Structure

All requests go to https://api.sportradar.com/mapping/ with the version v2:

GET https://api.sportradar.com/mapping/{access_level}/v2/en/{scope}/{urn}/{lookup}.{format}

access_level is trial or production, and format is json or xml. Note the language segment is fixed at en in this API's paths. The {scope} and {lookup} combination selects the endpoint: a scoping entity (sport, competition, season, or sport event) whose URN goes in the path, and the entity type whose mappings you want back.

The Endpoint Catalog

Nine lookups, grouped by the scoping entity in the path:

Mapping Lookups by ScopeThe URN you have decides the row; the pill is what you get back

SportSport Competition MappingsDaily Sport Event Mappingsthe daily lookup adds a date to the path

CompetitionCompetition Season Mappings

SeasonSeason Competitor MappingsSeason Player MappingsSeason Sport Event Mappings

Sport eventSport Event MappingsSport Event Competitor MappingsSport Event Player Mappings

All lookups are GET, forward-only (URN in, external IDs out), and return mappings only for the providers configured for your key.

The endpoint reference pages: Sport Competition Mappings, Daily Sport Event Mappings, Competition Season Mappings, Season Competitor Mappings, Season Player Mappings, Season Sport Event Mappings, Sport Event Mappings, Sport Event Competitor Mappings, and Sport Event Player Mappings.

Response Formats

Every lookup supports json and xml. The json and xml twins for the same sport event:

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

⚠️
Empty lists mean no providers are configured
A 200 with well-formed, empty mappings (as in the responses above, from a key with no providers configured) means the request worked but no mapping providers are configured for your API key. It is a configuration state, not an error. Contact Sportradar to configure the providers your integration needs; the same calls then return the mappings for those providers.

Pagination

List lookups return the X-Max-Results, X-Offset, and X-Result headers and accept start and limit parameters, paginating at the entity level (a page boundary never splits one entity's mappings). Pages carry up to 100 items; walk start until X-Result comes back smaller than the page size.

Errors

Unlike the Odds Comparison feeds, the Mapping API returns JSON error objects with a message:

400 for a malformed identifier:

GET https://api.sportradar.com/mapping/trial/v2/en/sport_events/not-a-urn/mappings.json
x-api-key: YOUR_API_KEY

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

404 for a well-formed identifier that does not exist:

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

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

Authentication failures return 403 with an HTML "Authentication Error" page (the same page as the other odds APIs); branch on the status code.
Rate-limit errors return 429 Too Many Requests; slow your request rate and retry, increasing the wait between attempts.

Cache Behavior

Mapping lookups carry a cache-control of max-age=300 (5 minutes). Mappings change rarely; a daily refresh of anything you cache locally is a comfortable cadence, with on-demand lookups for entities you have not seen before.