Our Elo rating for every active player, overall or on one surface, with the number of matches behind each rating.
Code verified October 10, 2026. It takes one call to get_ratings, 2 credits.
The call
surface is hard, clay or grass. Leave it out for the overall rating. active_since drops players who have stopped playing.
import requests
import pandas as pd
API_KEY = "YOUR_API_KEY"
resp = requests.post(
"https://mcp.acesapi.com/v1/get_ratings",
headers={"x-api-key": API_KEY},
json={
"surface": "clay",
"limit": 20,
},
timeout=60,
)
resp.raise_for_status()
data = resp.json()["data"]
clay = pd.DataFrame(data["ratings"])
print(clay[["rank", "name", "country", "rating", "surface_matches"]].head(10))
# 400 rating points is 10-to-1 odds.
gap = clay.loc[0, "rating"] - clay.loc[1, "rating"]
print(clay.loc[0, "name"], "beats", clay.loc[1, "name"], "on clay with probability", round(1 / (1 + 10 ** (-gap / 400)), 3))
You need requests and pandas (pip install requests pandas) and a free API key from AcesAPI.
What comes back
The data object, trimmed to the first rows. Every value is real output from the run above.
{
"tour": "ATP",
"surface": "clay",
"active_since": "2025-10-10",
"ratings": [
{
"rank": 1,
"rating": 2247,
"player_id": "3782",
"name": "Carlos Alcaraz",
"country": "ESP",
"surface_matches": 121,
"last_match": "2026-10-06"
},
{
"rank": 2,
"rating": 2209,
"player_id": "3623",
"name": "Jannik Sinner",
"country": "ITA",
"surface_matches": 106,
"last_match": "2026-07-12"
},
"...18 more"
],
"count": 20,
"method": "Elo from every completed singles match on the tour since 2007 (main draw and qualifying), start 1500, K = 250 / (matches + 5)^0.4; the surface rating counts only matches on that surface. Walkovers, defaults and retirements are not rated. At least 10 rated matches to be listed."
}
What to do next
- get_surface_splits (3 credits). A player's record by surface: sets, games, tiebreaks and deciding sets.
- get_head_to_head (3 credits). How two players have done against each other, by surface and in finals.
Originally published at acesapi.com.
Top comments (0)