---
updatedAt: 2026-10-06T07:23:24.000Z
agentTools:
siteIndex: https://developer.sportradar.com/llms.txt
projectIndex: https://developer.sportradar.com/odds/llms.txt
---
# Season Competitor Mappings
Get competitor mappings for a season.
Returns mappings between external IDs and Sportradar competitor IDs (SRIDs).
Only returns competitors from providers configured for the API key.
### Update Frequency
**TTL / Cache:** 5 minutes
**Data Updates:** As mappings are added or corrected
Cache behavior and refresh guidance: [Mapping API Basics](https://developer.sportradar.com/odds/docs/mapping-ig-api-basics)
> 📘 Resolving IDs Across Products
>
> Learn how to use the Season Competitor Mappings feed to resolve competitor IDs between Sportradar products in our [Resolving IDs Across Products](https://developer.sportradar.com/odds/docs/mapping-ig-resolving-ids) integration scenario.
***
## Data Points
| Attribute | Parent Element | Type | Description |
| --------- | -------------- | ---- | ----------- |
| `id` | `competitor` | String | Sportradar ID of a competitor
ex. `sr:competitor:3409` |
> See our [ID Types](https://developer.sportradar.com/getting-started/docs/id-types) section for more context on Sportradar ID types
| Attribute | Parent Element | Type | Description |
| --------- | -------------- | ---- | ----------- |
| `bookmaker_id` | `competitor` - `mapping` | String | Mapping entity ID
`sr:book:10358` represents Sportradar's UUIDs. Additional entities (or ID systems) can be configured
ex. `sr:book:10358` |
| `external_id` | `competitor` - `mapping` | String | External ID in the mapping entity's system
ex. `4353138d-4c22-4396-95d8-5f587d2df25c` |
# OpenAPI definition
```json
{
"openapi": "3.0.0",
"info": {
"title": "Mapping API",
"version": "2",
"x-sr-package": "mapping",
"x-sr-version": "v2"
},
"servers": [
{
"url": "https://api.sportradar.com/mapping/"
}
],
"security": [
{
"ApiKeyAuth": []
}
],
"paths": {
"/{access_level}/v2/en/seasons/{season_id}/competitor_mappings.{format}": {
"get": {
"summary": "Season Competitor Mappings",
"description": "Get competitor mappings for a season.\nReturns mappings between external IDs and Sportradar competitor IDs (SRIDs).\nOnly returns competitors from providers configured for the API key.\n",
"operationId": "getSeasonCompetitorMappings",
"parameters": [
{
"$ref": "#/components/parameters/access_level"
},
{
"$ref": "#/components/parameters/season_id"
},
{
"$ref": "#/components/parameters/format"
},
{
"description": "Starting position for pagination",
"example": 0,
"in": "query",
"name": "offset",
"schema": {
"default": 0,
"minimum": 0,
"type": "integer"
}
},
{
"description": "Maximum number of results to return",
"example": 100,
"in": "query",
"name": "limit",
"schema": {
"default": 100,
"maximum": 100,
"minimum": 1,
"type": "integer"
}
}
],
"responses": {
"200": {
"$ref": "#/components/responses/season_competitor_mappings"
},
"400": {
"description": "Bad Request - Invalid season ID format"
},
"404": {
"description": "Not Found - Season does not exist"
}
},
"tags": [
"mappings"
],
"x-sr-name": "season_competitor_mappings"
}
}
},
"components": {
"securitySchemes": {
"ApiKeyAuth": {
"type": "apiKey",
"in": "header",
"name": "x-api-key",
"description": "Your Sportradar API key"
}
},
"schemas": {
"competitor_with_mappings": {
"description": "Competitor with their external bookmaker mappings",
"properties": {
"id": {
"description": "Sportradar competitor ID",
"example": "sr:competitor:35",
"type": "string",
"xml": {
"attribute": true
}
},
"mappings": {
"description": "List of external bookmaker mappings for this competitor (sorted by bookmaker_id, then external_id)",
"items": {
"properties": {
"bookmaker_id": {
"description": "Bookmaker ID",
"example": "sr:book:10358",
"type": "string",
"xml": {
"attribute": true
}
},
"external_id": {
"description": "External ID in the bookmaker's system",
"example": "5b9aac82-f07e-411d-a4aa-8e645130b2cc",
"type": "string",
"xml": {
"attribute": true
}
}
},
"type": "object",
"xml": {
"name": "mapping"
}
},
"type": "array",
"xml": {
"name": "mappings",
"wrapped": true
}
}
},
"required": [
"id"
],
"type": "object",
"xml": {
"name": "competitor"
}
}
},
"responses": {
"season_competitor_mappings": {
"content": {
"application/json": {
"schema": {
"properties": {
"competitors": {
"description": "List of competitors with their mappings",
"items": {
"$ref": "#/components/schemas/competitor_with_mappings"
},
"type": "array"
},
"generated_at": {
"format": "date-time",
"type": "string"
}
},
"type": "object"
}
},
"application/xml": {
"schema": {
"properties": {
"generated_at": {
"format": "date-time",
"type": "string",
"xml": {
"attribute": true
}
},
"items": {
"$ref": "#/components/schemas/competitor_with_mappings"
}
},
"type": "object",
"xml": {
"name": "season_competitor_mappings",
"wrapped": true,
"x-sr-object-name": "SeasonCompetitorMappingsEndpoint"
}
}
}
},
"description": "OK",
"headers": {
"X-Max-Results": {
"description": "Total number of available competitors",
"schema": {
"example": 20,
"type": "integer"
}
},
"X-Offset": {
"description": "Starting position of results",
"schema": {
"example": 0,
"type": "integer"
}
},
"X-Result": {
"description": "Number of competitors returned in this response",
"schema": {
"example": 20,
"type": "integer"
}
}
}
}
},
"parameters": {
"access_level": {
"description": "The access level of your API key
`trial`, `production`",
"in": "path",
"name": "access_level",
"schema": {
"type": "string",
"enum": [
"trial",
"production"
],
"default": "trial"
},
"required": true
},
"season_id": {
"description": "Unique Id of a season
**Example:** `sr:season:x`",
"example": "sr:season:12345",
"in": "path",
"name": "season_id",
"required": true,
"schema": {
"pattern": "^sr:season:\\d+$",
"type": "string"
}
},
"format": {
"description": "Format returned
`json`, `xml`",
"in": "path",
"name": "format",
"schema": {
"type": "string",
"enum": [
"json",
"xml"
],
"default": "json"
},
"required": true
}
}
},
"externalDocs": {
"description": "Sportradar Developer Portal",
"url": "https://developer.sportradar.com/odds/reference/mapping-overview"
}
}
```