Overview

API Schema & Endpoint Guide

Find the right endpoint by starting with what you want to do. Base host: tennis-api-atp-wta-itf.p.rapidapi.com. atp= men's tennis (ATP, Challenger, ITF). wta = women's (WTA, ITF). There is no separate itf tour value.

What do you want to do?

Follow the lifecycle of a match

UPCOMING MATCHES → UPCOMING + PREDICTIONS & ODDS → LIVE: REST or Socket.IO → RESULTS & HISTORICAL DATA

1. Upcoming Matches

Use this section to find scheduled matches and factual match/H2H data — by date, date range, tournament, player, matchup and round. Available on all plans (FREE / PRO / ULTRA / MEGA). If you also need pre-match odds or prediction enrichment, use Upcoming Matches (With Predictions & Odds Data).

GET /tennis/v2/{type}/fixtures
GET /tennis/v2/{type}/fixtures/{date}
GET /tennis/v2/{type}/fixtures/{startDate}/{endDate}
GET /tennis/v2/{type}/fixtures/tournament/{tournamentId}
GET /tennis/v2/{type}/fixtures/player/{playerId}
GET /tennis/v2/{type}/fixtures/h2h/{player1Id}/{player2Id}

Open Upcoming Matches documentation →

2. Upcoming Matches (With Predictions & Odds Data)

Use this section when you need upcoming matches enriched with basic bookmaker odds and prediction-related data. Available on all plans; only the SportsAPI365 model win probabilities (modelPrediction) require ULTRA or MEGA. Keep these concepts separate:

• predictionSummary — bookmaker-implied view from headline odds
• modelPrediction — model win probabilities (separate object)
• preMatchOdds — bookmaker odds detail

GET /tennis/v2/upcoming/matches
GET /tennis/v2/upcoming/matches/{type}
GET /tennis/v2/upcoming/match-prediction/{type}/{player1}/{player2}   # MEGA only
GET /tennis/v2/aggregate/head-to-head/prediction/raw?player1=…&player2=…   # MEGA only
GET /tennis/v2/aggregate/head-to-head/model/prediction?player1=…&player2=…   # ULTRA / MEGA
GET /tennis/v2/upcoming/matchodds/{type}                             # Match Odds (All Markets)

Open Predictions & Odds documentation →

3. Live Scores, Stats & Odds

REST for current state; Socket.IO (MEGA) for push without polling. Live REST uses its own event id — do not send a core fixture ID to live odds endpoints.

GET /tennis/v2/extend/api/events/live
GET /tennis/v2/extend/api/ws-token          # MEGA → connect https://live.matchstat.com

Open Live REST → · Open Socket.IO →

4. Results & Historical Data

GET /tennis/v2/{type}/results/{date}
GET /tennis/v2/{type}/results/{startDate}/{endDate}
GET /tennis/v2/{type}/results/player/{playerId}
GET /tennis/v2/{type}/results/tournament/{seasonId}

Past champions / Grand Slam winners live here — not under Tours Calendar (Men & Women). Open Results →

Player and matchup data

5. Player Profiles & Career Stats

Find a player's numeric ID with search: GET /tennis/v2/search?search=Jannik Sinner returns results grouped by category (player_atp, player_wta, tournament_atp, tournament_wta); take the player's id (here 47275) and use it in the profile and H2H routes. Rankings and fixtures also carry player IDs. Open Players →

6. Head-to-Head Stats & Analysis

Historical / descriptive comparison. Forward-looking model predictions belong in Upcoming Matches (With Predictions & Odds Data). Open H2H →

Rankings and tournament data

7. Rankings

Historical ranking snapshots take DD.MM.YYYY or YYYY-MM-DD; match dates use YYYY-MM-DD. Open Rankings →

8. Tournaments & Draws

9. Tours Calendar (Men & Women)

Answers “what tournaments are happening when?”

GET /tennis/v2/{type}/tournament/calendar/{year}
GET /tennis/v2/calendar/active
GET /tennis/v2/calendar/{type}/filters

Active tournaments use tournament start dates (no stored end date) in the tennis week for the requested day. tour is atp, wta or both (default; all also works). Default omits Qualifying rows; pass qualifying=yes (or qualify=true) for qualifying event names and IDs.

GET /tennis/v2/calendar/active?tour=atp
GET /tennis/v2/calendar/active?tour=wta&date=2024-07-15
GET /tennis/v2/calendar/active?tour=atp&startDate=2026-09-21&endDate=2026-09-27
GET /tennis/v2/calendar/active?tour=atp&qualifying=yes

Open Tours Calendar (Men & Women) →

10. Potential Matchups

Possible future pairings — not confirmed fixtures. Open Potential Matchups →

11. Reference Data & Search

GET /tennis/v2/search
GET /tennis/v2/countries
GET /tennis/v2/court
GET /tennis/v2/round
GET /tennis/v2/ranking

Open Reference Data →

Understanding identifiers

• Player ID — numeric; from fixtures, rankings, player lists.
• Tournament / season ID — one year-edition; from calendar, then reuse on info / results / fixtures.
• Core fixture ID — scheduled-match row from Upcoming Matches.
• Live event id — live scores, timeline, live odds.
• Live matchId — player1Id-player2Id-tournamentId-roundId for point-by-point.

Plan access at a glance

Field-level restrictions (e.g. modelPrediction on FREE / PRO) return 200 and keep the field visible with the message "Upgrade Plan to see this". Restricted endpoints (MEGA only, or H2H Model Prediction on ULTRA / MEGA) return 403:

{
  "error": "plan_restricted",
  "message": "Your current plan does not include access to this data. Please upgrade via RapidAPI.",
  "requiredPlan": "MEGA",
  "upgradeUrl": "https://rapidapi.com/jjrm365-kIFr3Nx_odV/api/tennis-api-atp-wta-itf"
}

The message names where you subscribed: RapidAPI subscribers see "…Please upgrade via RapidAPI."; SportsAPI365.com subscribers see "…Please upgrade via SportsAPI365.com." with the matching upgradeUrl.

Reusable response schemas

These objects appear across many endpoints. Each endpoint's Response Properties table lists every field of its example; the definitions below are the shared meaning.

Player object

Tournament object

Plan-restricted field

LiveEvent object (REST and Socket.IO)

Odds entry (live odds routes)

Point-by-point set and game

Statistics metric (match statistics)

Common recipes