---
updatedAt: 2026-10-06T07:23:28.000Z
agentTools:
siteIndex: https://developer.sportradar.com/llms.txt
projectIndex: https://developer.sportradar.com/odds/llms.txt
---
# Season Player Mappings
Get player mappings for a season.
Returns mappings between external IDs and Sportradar player IDs (SRIDs).
Only returns players from providers configured for the API key.
Results are paginated by players (not individual mappings).
Players are sorted alphabetically by ID.
Mappings within each player 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 Season Player Mappings feed to resolve player 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` | `player` | String | Sportradar ID of a player
ex. `sr:player:608020` |
> 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` | `player` - `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` | `player` - `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}/player_mappings.{format}": {
"get": {
"summary": "Season Player Mappings",
"description": "Get player mappings for a season.\nReturns mappings between external IDs and Sportradar player IDs (SRIDs).\nOnly returns players from providers configured for the API key.\n\nResults are paginated by players (not individual mappings).\nPlayers are sorted alphabetically by ID.\nMappings within each player are sorted by bookmaker_id, then external_id.\n",
"operationId": "getSeasonPlayerMappings",
"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 players to return per page",
"example": 100,
"in": "query",
"name": "limit",
"schema": {
"default": 100,
"maximum": 100,
"minimum": 1,
"type": "integer"
}
}
],
"responses": {
"200": {
"$ref": "#/components/responses/season_player_mappings"
},
"400": {
"description": "Bad Request - Invalid season ID format"
},
"404": {
"description": "Not Found - Season does not exist"
}
},
"tags": [
"mappings"
],
"x-sr-name": "season_player_mappings"
}
}
},
"components": {
"securitySchemes": {
"ApiKeyAuth": {
"type": "apiKey",
"in": "header",
"name": "x-api-key",
"description": "Your Sportradar API key"
}
},
"schemas": {
"player_with_mappings": {
"description": "Player with their external bookmaker mappings",
"properties": {
"id": {
"description": "Sportradar player ID",
"example": "sr:player:35166",
"type": "string",
"xml": {
"attribute": true
}
},
"mappings": {
"description": "List of external bookmaker mappings for this player (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": "player"
}
}
},
"responses": {
"season_player_mappings": {
"content": {
"application/json": {
"schema": {
"properties": {
"generated_at": {
"format": "date-time",
"type": "string"
},
"players": {
"description": "List of players with their mappings (sorted by player ID)",
"items": {
"$ref": "#/components/schemas/player_with_mappings"
},
"type": "array"
}
},
"type": "object"
}
},
"application/xml": {
"schema": {
"properties": {
"generated_at": {
"format": "date-time",
"type": "string",
"xml": {
"attribute": true
}
},
"items": {
"$ref": "#/components/schemas/player_with_mappings"
}
},
"type": "object",
"xml": {
"name": "season_player_mappings",
"wrapped": true,
"x-sr-object-name": "SeasonPlayerMappingsEndpoint"
}
}
}
},
"description": "OK",
"headers": {
"X-Max-Results": {
"description": "Total number of available players",
"schema": {
"example": 3781,
"type": "integer"
}
},
"X-Offset": {
"description": "Starting position of results",
"schema": {
"example": 0,
"type": "integer"
}
},
"X-Result": {
"description": "Number of players 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"
}
}
```