How do I get tennis Elo ratings by surface in Python?
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. 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))
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",
"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.
More guides
Start with 500 free credits every month
No card. REST or MCP.