Soccer v3 to v4 Migration Guide

Soccer v4 is built on the Global API v2 framework, which introduces consistent terminology and structure across all Sportradar sport APIs. If you are already using any other Sportradar v2-framework API (such as Global Baseball v2), the patterns in Soccer v4 will feel familiar.

The enhancements of v4 are:

• Unified terminology and ID formats across sports.
• Season-oriented endpoints with more data per call.
• Expanded coverage: Over 650 unique competitions in a single package, up from the league-group-based model in v3.

⚠️

Action Required

Soccer v3 has moved to reduced support. Current Soccer v3 customers are encouraged to migrate to Soccer v4. This guide is designed to help you transition quickly and take advantage of everything v4 has to offer.

Terminology Changes

The most important change in v4 is the adoption of standardized terminology. The table below maps v3 terms to their v4 equivalents.

Example: Competitor ID

v3:

sr:team:44

v4:

sr:competitor:44

Example: Sport Event ID

v3:

sr:match:27428994

v4:

sr:sport_event:27428994

URL Structure Changes

The base URL and path structure have been updated in v4. The most visible change is the removal of the league_group path parameter, v4 uses a single global package rather than splitting access by region (eu, am, as, intl, etc.).

v3 URL Pattern

https://api.sportradar.us/soccer-{access_level}3/{league_group}/{language_code}/matches/{match_id}/timeline.{format}?api_key={key}

v4 URL Pattern

https://api.sportradar.com/soccer/{access_level}/v4/{language_code}/sport_events/{sport_event_id}/timeline.{format}?api_key={key}

Key differences:

v3 Access Level Values

Endpoint Changes

The tables below maps v3 endpoints to their v4 equivalents. Note that in several cases v4 consolidates what were previously separate endpoints.

New Feeds in v4

The following feeds have no direct v3 equivalent and are new in v4.

Coverage Model Changes

Coverage Properties

v3 used four named coverage tiers, Bronze, Silver, Gold, and Platinum, which you looked up via the coverage_info node. v4 replaces this with explicit coverage properties returned directly on each sport event response, making it programmatically clear what data is available for a given match.

v3 approach: Check coverage_info – level for bronze, silver, gold, or platinum, then infer what data is available.

v4 approach: Check the sport_event_properties object on the sport event, which contains explicit boolean flags:

"sport_event_properties": {
  "basic_play_by_play": true,
  "deeper_player_stats": true,
  "lineups": true,
  "ballspotting": false,
  "fun_facts": true,
  "scores": "live"
}

Design your integration to check these flags conditionally rather than inferring data availability from a coverage tier name.

League Group Removal

v3 required a league_group parameter in every URL (eu, am, as, intl, other, global) and a separate API key per league group. v4 removes this entirely, all 650+ competitions are accessible through a single API key and a single endpoint structure.

ID Migration & Mapping

Your stored v3 IDs (teams, players, matches) will need to be updated to v4 format. Only the prefixes change, the underlying numeric IDs are the same across v3 and v4. For example, sr:match:27428994 in v3 becomes sr:sport_event:27428994 in v4; the number 27428994 is unchanged. The same applies to team and tournament IDs.

Sportradar provides dedicated mapping endpoints to assist with this.

1. Call the Competitor Mappings endpoint to retrieve the v4 sr:competitor: ID for each of your stored v3 sr:team: IDs.
   HTTP

   GET /soccer/{access_level}/v4/{language_code}/competitors/{competitor_id}/mappings.{format}

2. Call the Player Mappings endpoint to retrieve updated IDs for any stored v3 player IDs.
   HTTP

   GET /soccer/{access_level}/v4/{language_code}/players/{player_id}/mappings.{format}

3. Use the Player Merge Mappings endpoint to resolve any player profiles that were merged in v4, ensuring you always reference the correct canonical ID.
4. Update stored match and tournament IDs.
   1. Historic match IDs use the sr:sport_event: prefix in place of sr:match:.
   2. Tournament IDs become competition IDs with the sr:competition: prefix in place of sr:tournament:.
   3. Team IDs use the sr:competitor: prefix in place of sr:team:.

Technical Considerations

Authentication

Authentication is required for all v4 API calls. Pass your API key via the x-api-key request header.

In v3, each league group required a separate API key. In v4, a single API key covers all competitions. If your current Soccer v3 access does not already include v4, contact your Sportradar account representative to request a Soccer v4 API key.

Update Your Data Models

Key things to update in your parsers and data models:

• Replace references to tournament, team, and match nodes with competition, competitor, and sport_event
• The sport_event_context object now contains competition, season, round, stage, and group context in a unified structure, replacing the separate tournament, tournament_round, and season elements from v3
• Statistics are nested under statistics > totals > competitors and statistics > periods > competitors
• Coverage information moves from coverage_info attributes to a structured coverage object with boolean property flags

Push Feed Filter Parameter Changes

In v3, the Push feeds accepted a match query parameter to filter by sport event. In v4, this becomes sport_event_id. Other filter parameters (season_id, sport_id, tournament_id) remain, but tournament_id now accepts sr:competition: format IDs.

Failover Behavior

The failover behavior in v4 is identical to v3. In the event of a scout feed outage, Sportradar activates Live Data Entry (LDE):

• Scenario 1: Basic events only (goals, cards, substitutions with player names). Deeper stats such as shots, corners, and assists will not be available.
• Scenario 2: Goals with player names only. All other event types and player associations will be unavailable.

Design your integration to handle reduced data gracefully.

Update Frequency & Caching

• The Sport Event Timeline has a 1-second TTL/cache
• For high-frequency live use cases, consider the Push Feeds to reduce polling overhead

Integration Resources

• OpenAPI Specs
  • Soccer v4
  • Soccer v4 Probabilities OpenAPI
• Postman
• Integration Guide
• Schema Download
• MCP Server
• Soccer v4 Reference Documentation
• Soccer v4 FAQ