---
updatedAt: 2026-10-06T07:23:32.000Z
agentTools:
siteIndex: https://developer.sportradar.com/llms.txt
projectIndex: https://developer.sportradar.com/odds/llms.txt
---
# Competition Season Mappings
Get season mappings for a competition.
Returns mappings between external IDs and Sportradar season IDs.
Only returns seasons from providers configured for the API key.
Results are paginated by seasons (not individual mappings).
Seasons are sorted alphabetically by ID.
Mappings within each season are sorted by bookmaker_id, then external_id.
### 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 Competition Season Mappings feed to resolve season 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` | `season` | String | Sportradar ID of a season
ex. `sr:season:60490` |
> 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` | `season` - `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` | `season` - `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/competitions/{competition_id}/season_mappings.{format}": {
"get": {
"summary": "Competition Season Mappings",
"description": "Get season mappings for a competition.\nReturns mappings between external IDs and Sportradar season IDs.\nOnly returns seasons from providers configured for the API key.\n\nResults are paginated by seasons (not individual mappings).\nSeasons are sorted alphabetically by ID.\nMappings within each season are sorted by bookmaker_id, then external_id.\n",
"operationId": "getCompetitionSeasonMappings",
"parameters": [
{
"$ref": "#/components/parameters/access_level"
},
{
"$ref": "#/components/parameters/competition_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 seasons to return per page",
"example": 100,
"in": "query",
"name": "limit",
"schema": {
"default": 100,
"maximum": 100,
"minimum": 1,
"type": "integer"
}
}
],
"responses": {
"200": {
"$ref": "#/components/responses/competition_season_mappings"
},
"400": {
"description": "Bad Request - Invalid competition ID format"
},
"404": {
"description": "Not Found - Competition does not exist"
}
},
"tags": [
"mappings"
],
"x-sr-name": "competition_season_mappings"
}
}
},
"components": {
"securitySchemes": {
"ApiKeyAuth": {
"type": "apiKey",
"in": "header",
"name": "x-api-key",
"description": "Your Sportradar API key"
}
},
"schemas": {
"season_with_mappings": {
"description": "Season with their external bookmaker mappings",
"properties": {
"id": {
"description": "Sportradar season ID",
"example": "sr:season:131129",
"type": "string",
"xml": {
"attribute": true
}
},
"mappings": {
"description": "List of external bookmaker mappings for this season (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": 12345,
"type": "string",
"xml": {
"attribute": true
}
}
},
"type": "object",
"xml": {
"name": "mapping"
}
},
"type": "array",
"xml": {
"name": "mappings",
"wrapped": true
}
}
},
"required": [
"id"
],
"type": "object",
"xml": {
"name": "season"
}
}
},
"responses": {
"competition_season_mappings": {
"content": {
"application/json": {
"schema": {
"properties": {
"generated_at": {
"format": "date-time",
"type": "string"
},
"seasons": {
"description": "List of seasons with their mappings (sorted by season ID)",
"items": {
"$ref": "#/components/schemas/season_with_mappings"
},
"type": "array"
}
},
"type": "object"
}
},
"application/xml": {
"schema": {
"properties": {
"generated_at": {
"format": "date-time",
"type": "string",
"xml": {
"attribute": true
}
},
"items": {
"$ref": "#/components/schemas/season_with_mappings"
}
},
"type": "object",
"xml": {
"name": "competition_season_mappings",
"wrapped": true,
"x-sr-object-name": "CompetitionSeasonMappingsEndpoint"
}
}
}
},
"description": "OK",
"headers": {
"X-Max-Results": {
"description": "Total number of available seasons",
"schema": {
"example": 247,
"type": "integer"
}
},
"X-Offset": {
"description": "Starting position of results",
"schema": {
"example": 0,
"type": "integer"
}
},
"X-Result": {
"description": "Number of seasons 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
},
"competition_id": {
"description": "Unique Id of a competition
**Example:** `sr:competition:x`",
"example": "sr:competition:123",
"in": "path",
"name": "competition_id",
"required": true,
"schema": {
"pattern": "^sr:competition:\\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"
}
}
```