Tennis v2 → v3 Migration Guide

1. Why this migration is happening

The Tennis v2 API is moving to a reduced support model. The API will continue to function as normal, but support will be limited: v2 will no longer receive stat corrections, post-match data fixes, coverage additions, or bug fixes, and no further development or enhancements will be made. The endpoints will keep responding, but the data behind them will progressively drift out of sync with corrections applied only to v3.

This change reflects our transition to a new data pipeline and supporting tooling, which will underpin all future tennis products.

All new development, data-quality work, and coverage expansion now happens exclusively in Tennis v3, the current stable release. The v2 reference overview already carries Sportradar's advisory that v3 is the current, stable version and that integrating with it is strongly recommended.

At a glance

• v2 stat fixes and corrections: stopping.
• v3 is the current stable version — integrate against it for all new and existing workloads.
• v3 follows the same General Sport API conventions used across other Sportradar sports (Soccer, Baseball, Basketball), so the shape will be familiar.
• Only one endpoint is lost outright (Tournament Ongoing, §4.3). Everything else has a v3 successor.
• Check entitlements before scoping. Basic match probabilities remain in the main package via Season Probabilities, but the extended Probability Feeds and Push Feeds are licensed separately (§2.1).

The accuracy argument is the one that matters most. This is not a cosmetic version bump. Once corrections stop landing in v2, any match data your users rely on for accuracy diverges from the corrected v3 record — silently, and progressively. That is the reason to move early rather than at the deadline.

1.1 Timeline

Recommendation: don't wait for that date to begin. Because v2 corrections stop then, any match data your users rely on for accuracy should be sourced from v3 well before then.

2. What does not change

These are identical across v2 and v3, confirmed field-by-field in both specs. Customers can leave this part of their integration alone.

Migration impact: no auth changes, no client credential changes, no base-URL changes. This is a path-and-payload migration only.

2.1 Entitlements to confirm before you build

2.2 Push Feeds — new in v3

v3 adds two streaming feeds with no v2 counterpart. Rather than polling, you open one long-lived HTTP connection and receive continuous updates:

curl -L -X GET 'https://api.sportradar.com/tennis/{access_level}/{version}/stream/events/subscribe' \
  -H 'x-api-key: {your_api_key}'

Practical notes for anyone evaluating them:

• Complement, not replacement. Push carries changes to events and statistics, but not match status updates, and is not 1:1 with REST. A complete integration still needs REST endpoints.
• No stateful session. There is no replay or memory of prior messages. After a disconnect, recover by calling the corresponding REST endpoint to backfill what you missed.
• Heartbeats every 5 seconds when no new data is available — absence of heartbeats is your disconnect signal.
• Client requirements: must follow an HTTP redirect (within one minute) and accept chunked transfer encoding. JSON only.
• Filter with query strings (e.g. sport_event_id) to narrow a connection; there is no cap on open connections.
• Handle re-sends. Events flagged updated: true repeat a previously sent id — replace your stored copy rather than appending.

3. The core conceptual change: v2 nouns become v3 nouns

This is the single most important thing for an integrator to understand. v3 is not a renumbered v2 — it adopts Sportradar's General Sport API vocabulary, shared across our other sport APIs. Nearly every resource is renamed, and one is genuinely restructured.

The tournament → competition + season split

In v2, a "tournament" conflated the recurring event with a specific edition of it. v3 separates them:

• A competition is the recurring tournament (e.g. ATP Bucharest, Romania Men Singles, sr:competition:3007).
• A season is one edition of it (e.g. …2025, sr:season:124323, with start_date, end_date, year, and a competition_id back-reference).

Any v2 code holding a single tournament_season_id must now decide, per call, whether it needs the competition ID or the season ID. This is the most likely source of migration bugs and deserves the most test coverage.

4. Endpoint mapping

v2 exposes 27 endpoints; v3 exposes 30. All are GET.

4.1 Direct or near-direct equivalents

4.2 Consolidations — several v2 calls become one v3 call

v2 split schedule and results into separate endpoints. v3 merges each pair into a single "summaries" feed carrying both scheduling and result data.

Migration impact: integrations that fire a schedule call and a results call per entity can halve those requests.

4.3 v2 endpoints that changed shape or were retired

One was reorganized; one was retired outright.

• Match Probabilities has a main-package replacement in Season Probabilities, which returns per-match probabilities for a whole season rather than one match at a time. Expect to change how you request them, not whether you can get them.
• Tournament Ongoing is the only outright capability loss — no v3 endpoint reproduces it.

4.4 New in v3 — no v2 equivalent

5. Response payload changes

5.1 Response envelope: one root element per endpoint

Both versions give each endpoint its own root element — there is no shared wrapper to code against.

Parsers keyed to a v2 root element name must be re-pointed to the v3 name for every endpoint.

5.2 Identifier prefixes change — the underlying IDs do not

The numeric identity of an entity is stable across versions. Sportradar IDs are database identifiers: a match is the same record in v2 and v3, and so is a season, competitor, or venue. What changes is the URN prefix the API wraps around that number, and which field carries it.

This is confirmed by the v2 XSD, where matchUrn and sportEventUrn are defined with the identical pattern sr:match:[0-9]+ — two names for one entity — and by v2's seasonExtended type, which already carries both a tournament_id and a competition_id attribute.

What this means in practice:

• A stored v2 match ID is not lost. sr:match:59383231 and sr:sport_event:59383231 refer to the same match. Re-prefixing is a valid transformation, not a lookup.
• Season, competitor, venue, category and complex IDs need no transformation at all — prefix and number are both unchanged.
• Tournament IDs are the one case needing care. sr:tournament: maps to sr:competition:, but because v2 conflated the recurring event with its current edition, a stored tournament ID may have been used where v3 expects a season ID. The number is stable; the entity you need may not be. Resolve those via Competition Seasons (§4.1).

Recommended approach. Re-prefix mechanically where the mapping is one-to-one (match → sport event). For tournament IDs, review each call site to decide whether the v3 endpoint takes competition_id or season_id before rewriting — this is the judgement step, not the string change.

IDs are stable over time, too. Match IDs do not change once created; the only exception is a match mistakenly created twice, where the duplicate is removed. Delays and suspensions do not affect match IDs. Season and venue IDs are likewise permanent. Use Sport Events Created / Updated / Removed to track new, changed, and duplicate-removed events, and Competitor Merge Mappings when two competitor records are merged (§4.4).

Note: the v3 XSDs type IDs as plain xs:string without pattern constraints. The v2 patterns above are from Tennis_v2.zip; the v3 prefixes are evidenced by the v3 OpenAPI spec, the portal's ID Handling guide, and change-log samples (sr:competition:3007, sr:season:124323, sr:sport_event:59383231).

Watch URL-encoding of URN IDs.
URN IDs contain colons (sr:season:124323). When they appear as path parameters, make sure your client encodes them correctly and consistently — mis-encoded colons are a common source of 4xx errors during migration. Test in the trial environment before cutover.

5.3 Statistics: 16 fields become 39

v2 carried 16 match statistics per team. v3 carries 39 per competitor.

Removed — exactly one field: receiver_points_won. It has no direct equivalent in v3. Integrations consuming it should review the v3 serve/return statistics listed below to determine the appropriate substitute for their use case.

Carried over unchanged (15): aces, double_faults, first_serve_successful, first_serve_points_won, second_serve_successful, second_serve_points_won, service_points_won, service_games_won, breakpoints_won, total_breakpoints, tiebreaks_won, games_won, points_won, max_games_in_a_row, max_points_in_a_row

New in v3 (24) — the bulk is a shot-quality breakdown absent from v2 entirely:

• Serve/return: service_points_lost, return_winners, return_errors, return_errors_unforced, returns_played, points_won_from_last_10
• Shot quality (winners / errors / unforced errors per stroke): forehand_*, backhand_*, volley_*, lob_*, drop_shot_*, overhead_stroke_*, groundstroke_*

Statistics are also restructured: v2 nested them under teams/team, v3 under periods[] and totals per competitor — so v3 gives per-set statistics, which v2 did not.

5.4 Coverage-dependent fields

v3 responses carry coverage.sport_event_properties with enhanced_stats, detailed_serve_outcomes, play_by_play, and a scores mode. Branch on these rather than assuming population — coverage varies across the five tiers. Season Info exposes the same flags at season level, so coverage can be checked before ingesting a season.

6. What's improved in v3

The migration is not only a rename — v3 brings capabilities v2 does not have.

• Ongoing data quality. The decisive one: v3 is where stat fixes and post-match corrections continue to land. v2 will not receive them once reduced support begins.
• Consistency with other Sportradar APIs. v3 matches the General Sport API structure used by Soccer, Baseball, Basketball and others, so multi-sport integrations share one mental model and often reusable code.
• Competition/Season model. Separating the recurring competition from its yearly seasons makes historical queries and year-over-year comparisons far cleaner — the change that costs the most to adopt is also the one that pays back most.
• Richer live options. Live Summaries, Live Timelines, and a 10-second Live Timelines Delta, plus optional low-latency Push Feeds (§2.2).
• Deeper statistics. 39 per-competitor fields vs. 16 in v2, including a full shot-quality breakdown, plus per-set statistics v2 did not provide (§5.3).
• Purpose-built change feeds. Sport Events Created / Updated / Removed and Competitor Merge Mappings make incremental syncing and ID hygiene first-class.
• Deeper doubles coverage. Dedicated doubles rankings, race rankings, and doubles-partner history.
• Fewer calls for the same data. Four v2 schedule/results pairs collapse into single summaries feeds (§4.2).

7. Migration checklist

1. Confirm entitlements first (§2.1). Probability Feeds and Push Feeds are licensed add-ons. Basic match probabilities remain available in the main package via Season Probabilities, so licensing is only a prerequisite if you need live, outright, or per-event probability detail.
2. Inventory current v2 calls. Map each to §4. Flag every use of tournament_season_id.
3. Resolve the tournament split. For each tournament_season_id, determine whether the v3 call needs competition_id or season_id. Where a stored tournament ID was standing in for an edition, resolve the right season via Competitions → Competition Seasons.
4. Update path vocabulary. matches→sport_events, players/double_teams→competitors, tournaments→competitions/seasons.
5. Collapse the consolidated calls (§4.2) — schedule + results become one summaries call.
6. Re-point probabilities. Replace Match Probabilities with Season Probabilities and select the match you need from the season response — the markets / outcomes shape is unchanged. Only move to the Probability Feeds add-on if you need live or outright probabilities (§2.1, §4.3).
7. Rebuild Tournament Ongoing. Filter Seasons or Competition Seasons on start_date / end_date to identify in-flight seasons; pair with Live Summaries if the need was live matches rather than active tournaments (§4.3).
8. Update response parsing per §5. In priority order:
   a. Re-point root element names (§5.1).
   b. Re-prefix stored IDs — sr:match: → sr:sport_event:, sr:tournament: → sr:competition:. The numbers are unchanged; season, competitor and venue IDs need no change at all (§5.2).
   c. Re-map match status. v2's flat sport_event_status attributes are nested in v3: live point state moves into game_state, and tiebreak scores into period_scores. ball_status, match_ended and period are removed — branch on status / match_status instead of match_ended, or a completed match will never register.
   d. Handle the removal of receiver_points_won — no direct v3 equivalent (§5.3).
9. Adopt Competitor Merge Mappings. Sportradar occasionally merges duplicate competitor profiles; this feed returns the surviving ID and retains entries for only one week. An integration that stores competitor IDs long-term should poll it weekly or risk silently holding dead IDs. Easy to overlook, expensive to debug.
10. Adopt the delta feeds. Live Timelines Delta, Sport Events Created / Updated / Removed reduce polling load.
11. Branch on coverage flags (§5.4).
12. Check URL-encoding of URN IDs in path parameters (§5.2) — test in the trial environment.
13. Run v2 and v3 in parallel and diff on live data. Resolve discrepancies before cutover.
14. Verify against the v3 OpenAPI spec, then cut over before reduced support begins.

8. Reference

Start here

• Sportradar Marketplace — where to obtain Tennis v3 access
• Tennis v3 Reference — endpoint list, parameters, schemas, and the v3 API map
• Tennis v3 Integration Guide
  • API Basics — auth, access levels, formats, language codes
  • ID Handling — URN structure and ID stability (§5.2)
  • Push Feeds — streaming setup and payloads (§2.2)

Specifications & schemas

• Tennis v3 OpenAPI
• Tennis v3 Probabilities OpenAPI
• Tennis v3 Schema (XSD) — direct download
• Tennis v2 Schema (XSD) — direct download; useful for diffing your current integration
• Statistics Summary — field-by-field statistics definitions (§5.3)

Add-on packages

• Probability Feeds — overview and licensing (§2.1, §4.3)
• Push Feeds endpoints — Push Events and Push Statistics reference

Comparing against v2

• Tennis v2 Reference — for side-by-side comparison during migration

Coverage & timeline

• Coverage Matrix — competitions and data by package
• Tennis v3 Change Log
• Sportradar Change Log — authoritative timeline for deprecations

Tooling

• Postman workspace — fork or follow the Tennis collection to get updates automatically
• MCP Server — connect an AI assistant directly to the Tennis API feeds