DEV Community

noah
noah

Posted on Originally published at acesapi.com

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. 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))
Enter fullscreen mode Exit fullscreen mode

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."
}
Enter fullscreen mode Exit fullscreen mode

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)