Overview
FAQ & Troubleshooting
Most support questions come from mixing path families, player identifiers, pagination names, or date formats. Use this page as a checklist before you change your integration.
Full walkthrough: Getting Started. Endpoint-by-endpoint parameters stay on each reference page. If a call still fails, compare your URL, query string, and host header with the example on that page â not a shortened playground path.
Jump to a topic
- I get 403 Forbidden resource. What did I send wrong?
- Should I pass a player ID, a display name, or a slug?
- Which pagination parameters should I send?
- What date format does each endpoint expect?
- Why do my fixture filters do nothing, and why do I see doubles?
- Where is the ITF / Challenger tour type?
- The response is empty. Is the API down?
- How do I connect fixtures, live events, odds, and point-by-point?
- Which plan do I need for live odds and WebSockets?
- Why is Challenger / ITF missing from H2H or player stats?
- How do I load a player photograph?
- GET /tennis/v2/ranking/atp says it needs a date or group.
- H2H breakdown returns 404 / No such player.
I get 403 Forbidden resource. What did I send wrong?
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:
| Family | Host | Path starts with |
|---|---|---|
| Core (fixtures, players, rankings, tournaments) | tennis-api-atp-wta-itf.p.rapidapi.com | /tennis/v2/{atp|wta}/ |
| Name-based stats, H2H, calendar, predictions | tennis-api-atp-wta-itf.p.rapidapi.com | /tennis/v2/ + module (profile, h2h, tournament, upcomingâĻ). |
| Live scores, odds, point-by-point | tennis-api-atp-wta-itf.p.rapidapi.com | /tennis/v2/extend/api/ |
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.
Should I pass a player ID, a display name, or a slug?
| Route family | Use this | Do not use |
|---|---|---|
/tennis/v2/{atp|wta}/player/âĻ and fixtures | Numeric ID, e.g. 68074 | Carlos Alcaraz (returns 400 â ID must be an integer) |
/tennis/v2/profile/âĻ and name-based H2H (/tennis/v2/h2h/âĻ) | URL-encoded display name Carlos%20Alcaraz, or the numeric ID | Slug alcaraz-carlos â {"err":"Player not found"} |
/tennis/v2/extend/api/event/get/âĻ | Display names plus date YYYY-MM-DD | Core fixture IDs |
Search (/tennis/v2/search?search=) returns matching names, not numeric IDs. Read IDs from rankings, fixtures (player1Id / player2.id), or the core player list.
Which pagination parameters should I send?
| Family | Page | Page size | Notes |
|---|---|---|---|
| Core | pageNo | pageSize | Max 500 (larger values are reduced). Response includes hasNextPage. |
Name-based routes (/profile, /h2h, /upcomingâĻ) | page | limit | Both styles work on every route: page = pageNo and limit = pageSize. |
Do not try to dump an entire calendar or career in one call. Walk pages until hasNextPage is false or data is empty.
What date format does each endpoint expect?
| Endpoint | Format | Example |
|---|---|---|
| Core fixtures path | YYYY-MM-DD | /tennis/v2/atp/fixtures/2026-09-15 |
| Dated rankings snapshot query | DD.MM.YYYY plus required group | /tennis/v2/ranking/atp?date=14.09.2026&group=singles |
| Live event by players | YYYY-MM-DD | /tennis/v2/extend/api/event/get/Jannik%20Sinner/Carlos%20Alcaraz/2026-09-14 |
Dated rankings reject YYYY-MM-DD with Invalid date format. Use DD.MM.YYYY. Omitting date or group returns a JSON error body with HTTP 200 â check the error field, not only the status code.
Why do my fixture filters do nothing, and why do I see doubles?
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=20Combine 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.
Where is the ITF / Challenger tour type?
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.
The response is empty. Is the API down?
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/odd2asnullon historical matches â coverage is not every bookmaker on every past match.
HTTP 404 means the path or identifier does not exist. Some advanced routes also return HTTP 200 with {"error":"âĻ"} or {"err":"Player not found"} â always inspect the JSON.
How do I connect fixtures, live events, odds, and point-by-point?
These identifiers are different namespaces:
- Fixture ID â core schedule row.
- Live
idâ odds, timeline, live score. - Live
matchIdâ four numbers joined by hyphens, used as PBP path segments{p1}/{p2}/{tournamentId}/{roundId}.
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.
Which plan do I need for live odds and WebSockets?
- Core fixtures, players, rankings, and tournaments are available on standard REST plans.
- Solid REST live scores and odds are on Ultra and Mega.
- Socket.IO push is Mega only. Lower plans receive
WebSocket access requires MEGA planfrom/ws-token.
Subscribe on RapidAPI, evaluate with your key, and downgrade or cancel there if the plan is not a fit. RapidAPI daily/monthly quotas are separate from the 100 requests/minute throttle.
Why is Challenger / ITF missing from H2H or player stats?
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.
How do I load a player photograph?
GET the image path from a profile payload. The file is a JPEG, for example:
/tennis/v2/ms-api/uploads/Photo/atp/05992.jpgPrefix 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.
GET /tennis/v2/ranking/atp says it needs a date or group.
Both query parameters are required:
/tennis/v2/ranking/atp?date=14.09.2026&group=singles&page=1&limit=10group 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.
H2H breakdown returns 404 / No such player.
Breakdown is a single-player career split, not a two-player rivalry:
/tennis/v2/h2h/breakdown/atp/Carlos%20AlcarazTwo-player stats use /tennis/v2/h2h/stats/{atp|wta}/{player1}/{player2}. Putting two names into the breakdown path returns No such player.