get_ratings

2 creditsBasic lookupPOST /v1/get_ratings

Our Elo ratings, overall or by surface

Use it when you want our Elo ratings, best first, overall or on one surface, for active players.

Parameters

surfaceenum: hard | clay | grass | carpetoptional: Rank by the surface rating instead of overall.
active_sincestringoptional: Only players with a rated match since this date, YYYY-MM-DD (default one year ago).
limitintegeroptional: Max players (default 50).

Notes

Over MCP, ask for it in plain English and the client calls get_ratings itself. Point any MCP client at https://mcp.acesapi.com/mcp?key=YOUR_API_KEY.
Each call costs 2 credits, taken before it runs and refunded if the server errors.
Not the call you need? Find the right call by what you are trying to answer.

Request

curl -X POST https://mcp.acesapi.com/v1/get_ratings \
  -H "Content-Type: application/json" \
  -H "x-api-key: YOUR_API_KEY" \
  -d '{
  "surface": "clay",
  "limit": 5
}'

Response

json

{
  "tour": "ATP",
  "surface": "clay",
  "active_since": "2025-10-08",
  "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"
    },
    {
      "rank": 3,
      "rating": 2086,
      "player_id": "2375",
      "name": "Alexander Zverev",
      "country": "GER",
      "surface_matches": 240,
      "last_match": "2026-10-04"
    }
  ],
  "count": 5,
  "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."
}