FAQ & Troubleshooting

Almost always the host header does not match the product, or the path prefix does not belong to that product. On the umbrella listing Tennis API - ATP WTA ITF use:

Send both X-RapidAPI-Key and X-RapidAPI-Host: tennis-api-atp-wta-itf.p.rapidapi.com on every request. A missing or mismatched host returns 403 with Forbidden resource.

Search (/tennis/v2/search?search=) returns matching players with their numeric id (plus name, birthday and country), so a search result can go straight to a profile or H2H call. IDs also appear in rankings and fixtures (player1Id / player2.id).

Do not try to dump an entire calendar or career in one call. Walk pages until hasNextPage is false or data is empty.

Dated rankings reject YYYY-MM-DD with Invalid date format. Use DD.MM.YYYY. Omitting date or group returns HTTP 400 with a message naming the missing parameter (e.g. Needs date in query params!).

Fixtures do not take top-level query keys such as ?PlayerGroup=singles. Put filters in one filter parameter:

/tennis/v2/atp/fixtures?filter=PlayerGroup:singles&pageNo=1&pageSize=20

Combine keys with semicolons, and values with commas: filter=PlayerGroup:singles;TourCountry:USA,FRA. Rank, court, and country filters only apply when you also send the matching include (for example include=tournament).

The default fixture list includes doubles (names contain /). Live events are singles-only.

Dataset to query. atp= men's tennis across all supported levels, including Grand Slams, ATP Tour, Challengers and ITF. wta= women's tennis across all supported levels, including Grand Slams, WTA Tour and ITF. There is no separate itf value — itf or challenger in the path returns 400. Filter fixtures with TourRank using ids from GET /ranking(Challenger/ITF > $10K is 1, Grand Slam is 4) and include=tournament. The filterable calendar can also filter by level name.

HTTP 200 with data: [] and hasNextPage: false means the request was valid and there is nothing for that date, player, or filter. That is not an outage.

Typical cases:

• Fixtures for a date with no scheduled matches.
• Filterable calendar level=3 (numeric IDs return no rows — use the name from /calendar/{tour}/filters, e.g. level=Grand Slam).
• Potential fixtures for a tournament that has already finished.
• Odds fields odd1 / odd2 as null on historical matches — coverage is not every bookmaker on every past match.

HTTP 404 means the URL matches no endpoint (a wrong path). An unknown player, tournament or match, or no data for a date or filter, returns HTTP 200 with an empty result: {} for single objects or the usual list shape with an empty list. Invalid input returns 400 with {"error": true, "message": "…"}.

These identifiers are different namespaces:

• Numeric matchId / fixture id — from Upcoming Matches, Results, or curated upcoming. Use with /tennis/v2/matches/{matchId} and its detail routes (prediction, odds, stats, live). Upcoming rows also carry liveMatchId and links.live to reach the live event in one call.
• Live id — odds, timeline, live score on the Live page.
• Live hyphenated matchId — four numbers joined by hyphens, used as PBP path segments {p1}/{p2}/{tournamentId}/{roundId}. Not the same as the numeric upcoming matchId.

REST /tennis/v2/extend/api/events/live is a snapshot. Near-real-time push needs the MEGA plan, /tennis/v2/extend/api/ws-token, then Socket.IO at https://live.matchstat.com. See Socket.IO Integration.

Bookmaker objects use short legacy keys. They are not renamed so existing clients keep working:

• k1 / k2 — match-winner odds for player 1 / player 2
• total + ktb / ktm — game total line and over / under prices
• f1 / f2 + kf1 / kf2 — game handicap and prices
• k20, k21, … — correct set-score markets when offered

Full table: Predictions → Match odds and Getting Started.

No. Prefer date and startTime (ISO-8601 UTC). timeGame is a legacy field; when the source has no separate local string it may be null even though date has the schedule. On dated fixture routes the API often mirrors date into timeGame when the column is empty. Live boards use startTimestamp (Unix seconds).

If date / startTime are also null, the order of play for that match has not been published yet; the time is filled in once the tournament schedules it, and the match appears instantly in the live feed when it starts.

See Getting Started → Match start times.

• All plans (FREE / PRO / ULTRA / MEGA): every endpoint — fixtures, results, players, rankings, H2H, tournaments, live scores, live and pre-match odds (all markets), point-by-point, timeline, match statistics, odds history, comparison and arbitrage. FREE and PRO have identical access; FREE differs only by quota.
• ULTRA / MEGA: SportsAPI365 model win probabilities (modelPrediction and H2H Model Prediction).
• MEGA only: Socket.IO push (token from GET /tennis/v2/extend/api/ws-token; /tennis/v2/ws-token does not exist) and the written predictions (Match Prediction & Analysis Paragraph, H2H Prediction Analysis).

Plan rate limits are 4 / 10 / 25 / 50 requests per second for FREE / PRO / ULTRA / MEGA; RapidAPI daily/monthly quotas also apply. Subscribe on RapidAPI, evaluate with your key, and downgrade or cancel there if the plan is not a fit.

Many advanced stats and H2H aggregates default to main-tour matches. Send includeAll=true when you need Challenger and ITF included. Surface filters on those routes use court (for example court=Clay), not surface=, unless the endpoint table says otherwise.

GET the image path from a profile payload. The file is a JPEG, for example:

/tennis/v2/ms-api/uploads/Photo/atp/68074.jpg

Prefix that path with the same host you already use. The file name is the player id padded to five digits. Do not call the legacy /tennis/api2/uploads/… prefix.

Both query parameters are required:

/tennis/v2/ranking/atp?date=14.09.2026&group=singles&page=1&limit=10

group is singles, doubles, race, surface, or prize. There is no dated path such as /ranking/atp/14.09.2026.

For current official lists without a historical date, use core /tennis/v2/{atp|wta}/ranking/singles.

Breakdown is a single-player career split, not a two-player rivalry:

/tennis/v2/h2h/breakdown/atp/Carlos%20Alcaraz

Two-player stats use /tennis/v2/h2h/stats/{atp|wta}/{player1}/{player2}. Putting two names into the breakdown path finds no such player, so the response is empty ({}).