How do I get a tennis tournament draw and results in Python?
A tournament's whole draw by round, with scores by set. The China Open had 31 main-draw matches and Novak Djokovic won the final.
Code verified October 12, 2026. One call to get_tournament, 2 credits.
The call
tournament_id comes from list_tournaments. A live event returns the rounds played so far. draw takes main, qualifying or all. Pass league: "wta" for the women's tour.
import requests
import pandas as pd
API_KEY = "YOUR_API_KEY"
resp = requests.post(
"https://mcp.acesapi.com/v1/get_tournament",
headers={"x-api-key": API_KEY},
json={
"tournament_id": "959-2026",
},
timeout=60,
)
resp.raise_for_status()
data = resp.json()["data"]
event = data["tournament"]
print(event["name"], event["city"], event["surface"], "- champion", data["champion"]["name"], "over", data["runner_up"]["name"])
matches = pd.DataFrame([dict(m, round_name=r["round"]) for r in data["rounds"] for m in r["matches"]])
print(matches.groupby(["round_order", "round_name"]).size())
final = matches[matches["round_name"] == "Final"].iloc[0]
print(final["player1"], "vs", final["player2"], final["score"])
print("matches decided in three sets or more:", int((matches["sets1"] + matches["sets2"] >= 3).sum()), "of", len(matches))
Replace YOUR_API_KEY with a key from your dashboard. Python needs requests and pandas (pip install requests pandas). JavaScript runs on Node 18 or newer, or in the browser.
What comes back
The data object of the response, trimmed to the first rows. Every field is real output from the run above.
{
"tour": "ATP",
"tournament": {
"tournament_id": "959-2026",
"espn_tournament_id": 959,
"name": "China Open",
"season": 2026,
"start_date": "2026-09-27",
"end_date": "2026-10-12",
"city": "Beijing",
"country": "China PR",
"major": false,
"surface": "hard",
"indoor": false,
"status": "final"
},
"champion": {
"player_id": "296",
"name": "Novak Djokovic"
},
"runner_up": {
"player_id": "2651",
"name": "Alex de Minaur"
},
"rounds": [
{
"round": "Round 1",
"round_order": 11,
"draw": "main",
"matches": [
{
"match_id": "183447",
"tournament_id": "959-2026",
"tournament": "China Open",
"season": 2026,
"surface": "hard",
"indoor": false,
"starts_at": "2026-09-30T03:10:00.000Z",
"match_date": "2026-09-30",
"draw": "main",
"round": "Round 1",
"round_order": 11,
"court": "Capital Group Diamond",
"player1_id": "2367",
"player1": "Karen Khachanov",
"player1_country": "RUS",
"seed1": null,
"player2_id": "3209",
"player2": "Felix Auger-Aliassime",
"player2_country": "CAN",
"seed2": 2,
"winner_id": "2367",
"status": "final",
"outcome": "completed",
"score": "6-3 6-3",
"sets1": 2,
"sets2": 0,
"games1": 12,
"games2": 6,
"sets": [
{
"set_no": 1,
"games1": 6,
"games2": 3,
"tiebreak1": null,
"tiebreak2": null,
"winner": 1
},
{
"set_no": 2,
"games1": 6,
"games2": 3,
"tiebreak1": null,
"tiebreak2": null,
"winner": 1
}
]
},
{
"match_id": "183461",
"tournament_id": "959-2026",
"tournament": "China Open",
"season": 2026,
"surface": "hard",
"indoor": false,
"starts_at": "2026-09-30T05:50:00.000Z",
"match_date": "2026-09-30",
"draw": "main",
"round": "Round 1",
"round_order": 11,
"court": "Lotus",
"player1_id": "2337",
"player1": "Jan-Lennard Struff",
"player1_country": "GER",
"seed1": null,
"player2_id": "4010",
"player2": "Thiago Agustin Tirante",
"player2_country": "ARG",
"seed2": null,
"winner_id": "2337",
"status": "final",
"outcome": "completed",
"score": "6-1 6-4",
"sets1": 2,
"sets2": 0,
"games1": 12,
"games2": 5,
"sets": [
{
"set_no": 1,
"games1": 6,
"games2": 1,
"tiebreak1": null,
"tiebreak2": null,
"winner": 1
},
{
"set_no": 2,
"games1": 6,
"games2": 4,
"tiebreak1": null,
"tiebreak2": null,
"winner": 1
}
]
},
"...14 more"
]
},
{
"round": "Round 2",
"round_order": 12,
"draw": "main",
"matches": [
{
"match_id": "183439",
"tournament_id": "959-2026",
"tournament": "China Open",
"season": 2026,
"surface": "hard",
"indoor": false,
"starts_at": "2026-10-02T05:10:00.000Z",
"match_date": "2026-10-02",
"draw": "main",
"round": "Round 2",
"round_order": 12,
"court": "Lotus",
"player1_id": "2635",
"player1": "Alex Molcan",
"player1_country": "SVK",
"seed1": null,
"player2_id": "2367",
"player2": "Karen Khachanov",
"player2_country": "RUS",
"seed2": null,
"winner_id": "2367",
"status": "final",
"outcome": "completed",
"score": "7-5 6-3",
"sets1": 0,
"sets2": 2,
"games1": 8,
"games2": 13,
"sets": [
{
"set_no": 1,
"games1": 5,
"games2": 7,
"tiebreak1": null,
"tiebreak2": null,
"winner": 2
},
{
"set_no": 2,
"games1": 3,
"games2": 6,
"tiebreak1": null,
"tiebreak2": null,
"winner": 2
}
]
},
{
"match_id": "183442",
"tournament_id": "959-2026",
"tournament": "China Open",
"season": 2026,
"surface": "hard",
"indoor": false,
"starts_at": "2026-10-02T11:25:00.000Z",
"match_date": "2026-10-02",
"draw": "main",
"round": "Round 2",
"round_order": 12,
"court": "Lotus",
"player1_id": "2726",
"player1": "Hubert Hurkacz",
"player1_country": "POL",
"seed1": null,
"player2_id": "10427",
"player2": "Arthur Gea",
"player2_country": "FRA",
"seed2": null,
"winner_id": "2726",
"status": "final",
"outcome": "completed",
"score": "7-6(5) 6-7(5) 6-2",
"sets1": 2,
"sets2": 1,
"games1": 19,
"games2": 15,
"sets": [
{
"set_no": 1,
"games1": 7,
"games2": 6,
"tiebreak1": 7,
"tiebreak2": 5,
"winner": 1
},
{
"set_no": 2,
"games1": 6,
"games2": 7,
"tiebreak1": 5,
"tiebreak2": 7,
"winner": 2
},
"...1 more"
]
},
"...6 more"
]
},
"...3 more"
],
"count": 31
}What to do next
- list_tournaments (1 credit). Find the tournament_id for any event and season.
- get_match (2 credits). One match with its odds and ratings.
More guides
Start with 500 free credits every month
No card. REST or MCP.