Getting Started

Your First Request

Go from API key to your first successful Tennis API request in a few minutes. Base URL: https://tennis-api-atp-wta-itf.p.rapidapi.com.

1. Subscribe and get your API key

The Tennis API is accessed through RapidAPI.

1. Subscribe to the Tennis API - ATP WTA ITF product.
2. Choose the plan that includes the data you need.
3. Copy your X-RapidAPI-Key.

One product, one RapidAPI host

https://tennis-api-atp-wta-itf.p.rapidapi.com

Every REST request should include:

X-RapidAPI-Key: YOUR_RAPIDAPI_KEY
X-RapidAPI-Host: tennis-api-atp-wta-itf.p.rapidapi.com

2. Choose the right data family for what you need

For players, H2H, rankings, tournaments, draws, potential matchups and reference data, use the Endpoint Guide.

3. Make your first request

A simple first request is the men's upcoming fixtures feed (atp dataset):

curl --request GET \
  --url 'https://tennis-api-atp-wta-itf.p.rapidapi.com/tennis/v2/atp/fixtures?pageNo=1&pageSize=5&filter=PlayerGroup:singles' \
  --header 'X-RapidAPI-Host: tennis-api-atp-wta-itf.p.rapidapi.com' \
  --header 'X-RapidAPI-Key: YOUR_RAPIDAPI_KEY'

This returns scheduled men's singles matches and useful identifiers (player IDs, tournament info).

Upcoming matches with odds and prediction data (all plans)

Same request on the enriched feed. Available on every plan; modelPrediction is filled on ULTRA / MEGA and shows Upgrade Plan to see this on FREE / PRO.

curl --request GET \
  --url 'https://tennis-api-atp-wta-itf.p.rapidapi.com/tennis/v2/upcoming/matches/atp' \
  --header 'X-RapidAPI-Host: tennis-api-atp-wta-itf.p.rapidapi.com' \
  --header 'X-RapidAPI-Key: YOUR_RAPIDAPI_KEY'

4. Type values: atp and wta

Supported coverage can include Grand Slams, ATP/WTA events, Challengers and ITF events. There is no separate itf type value: ITF matches are included in theatp (men) or wta (women) dataset where supported.

5. Understand the main URL patterns

Always copy the exact path shape from the endpoint reference.

6. Player, tournament and match identifiers

Player IDs

Every player parameter on the core, H2H, fixtures, results, rankings and match routes accepts the numeric ID or the display name: 47275 and Jannik Sinner return the same response. Names match case-insensitively within the tour in the path (atp or wta); a name shared by several players returns 400 listing their IDs. IDs are the most reliable choice; they come from fixtures, rankings, the core player list and every response that includes a player. In a raw URL the space is sent as %20; RapidAPI, Postman and HTTP libraries encode it for you.

Exceptions on the live service: Event by Players, Point-by-Point by Player Names, Odds by player names, H2H Model Prediction and H2H Prediction Analysis take names only; Point-by-Point by IDs takes IDs only.

Tournament IDs

A season/edition ID identifies a particular year of an event. Use Tours Calendar (Men & Women) to discover editions and Tournaments & Draws for a known tournament or draw.

7. Dates, times and pagination

Match start times

Use date / startTime(ISO-8601 UTC) as the scheduled start and convert to the user's timezone in your app. timeGame is a legacy field. A nullstart time means the order of play for that match has not been published yet (typical for later rounds and next week's draws); the time is filled in as soon as the tournament schedules it. As soon as a match goes live it appears instantly in the live match feed.

Pagination

Every paginated list accepts either naming style: page = pageNo and limit = pageSize. Responses return both pairs (page, pageNo, pageSize, limit) plus hasNextPage — continue until it is false. Past the last page a list returns an empty data array with hasNextPage: false. A lookup that finds nothing at all (unknown player, tournament or match) returns an empty object {} with no pagination fields. That empty object carries an X-Empty-Reason response header saying why (e.g. No live event for matchId=1300. or No match found for matchId=131779990.), so an unknown id can be told apart from a real match that has no data yet. The body stays {}.

Odds field names

Bookmaker odds objects use short keys: id_b_o bookmaker (1 = Marathonbet, 2 = Pinnacle); k1 / k2 match-winner odds for player 1 / player 2; total the line the over/under refers to; ktb / ktm over / under odds for that line; f1 / f2 handicap and kf1 / kf2 its odds; k20, k21, … correct set-score odds. The two bookmakers quote different markets under the same keys, so rows name the unit: totalUnit and handicapUnit are games on Marathonbet (total 22.5, handicap 4.5) and sets on Pinnacle (total 2.5, handicap 1.5). Never compare a games line with a sets line. The full-market odds object is on all plans; preMatchOdds repeats the headline match-winner prices in a simpler shape. Full table on Match Odds (All Markets).

8. Upcoming data: factual H2H, odds and predictions

Upcoming Matches — all plans

Factual schedule data. Fixtures return factual H2H with include=h2h (h2h.player1AllWins / h2h.player2AllWins); the upcoming feed returns h2h as a score string (e.g. 4-1) plus h2hSummary. Public docs do not advertise odds for new clients; legacy odds fields may still be returned for backwards compatibility.

Upcoming Matches (With Predictions & Odds Data) — all plans

• predictionSummary = bookmaker-implied view (FREE/PRO OK)
• preMatchOdds = pre-match match-winner odds (FREE/PRO OK)
• odds = full bookmaker markets (totals, handicap, set scores) — all plans
• modelPrediction = SportsAPI365 model win probabilities — ULTRA / MEGA; FREE/PRO get a plan_restricted object

9. Live data: REST or Socket.IO

REST — request the current board or match state (/extend/api/events/live).

Socket.IO — MEGA only. Get a token via /extend/api/ws-token, then connect to https://live.matchstat.com with the Socket.IO token (not the RapidAPI key). See Real-time (Socket.IO) Integration.

10. Plan restrictions and errors

A restricted endpoint (MEGA only, or H2H Model Prediction on ULTRA / MEGA) returns 403 Forbidden:

{
  "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.

When only a field is restricted (e.g. modelPrediction), the endpoint still returns 200 OK and keeps the field visible:

{
  "modelPrediction": {
    "available": false,
    "error": "plan_restricted",
    "message": "Upgrade Plan to see this",
    "requiredPlan": "ULTRA",
    "upgradeUrl": "https://rapidapi.com/jjrm365-kIFr3Nx_odV/api/tennis-api-atp-wta-itf"
  }
}

An empty result with HTTP 200 means nothing matched that identifier, date, filter or page. For {}, read the X-Empty-Reason response header for the cause.

11. Rate limits

Plan limits are 4 / 10 / 25 / 50 requests per second for FREE / PRO / ULTRA / MEGA (see the capacity table above). These per-second plan limits are what govern your requests; RapidAPI monthly / daily quotas also apply. A request over the limit returns 429 — wait before retrying. For live UIs that would poll heavily, MEGA customers should prefer Socket.IO.

12. Where to go next

Authenticate here → use the Endpoint Guideto select the data family → read that endpoint's parameter and response tables before coding.

• Upcoming Matches
• Upcoming Matches (With Predictions & Odds Data)
• Live Scores, Stats & Odds
• Real-time (Socket.IO) Integration
• Results & Historical Data
• Player Profiles & Career Stats
• Head-to-Head Stats & Analysis
• Rankings
• Tournaments & Draws
• Tours Calendar (Men & Women) — schedule and Active Tournaments
• Potential Matchups
• Reference Data & Search
• FAQ & Troubleshooting