Introduction

The ATP Rankings API provides programmatic access to historical ATP tennis rankings data spanning from 1973 to present. All endpoints return JSON responses and require no authentication.

Base URL: https://atp-rankings-data-visualization.onrender.com

Features

  • Access over 2,600 weeks of ATP rankings data
  • Retrieve complete rankings for any specific week
  • Search for players with autocomplete functionality
  • Get comprehensive player statistics and career facts
  • Access time-series data for player rankings and points
  • Get historical weeks at number 1 statistics for all players
  • Interactive player comparison tool with career graphs
  • Weeks at #1 histogram visualization
  • JSON response format for easy integration
  • No rate limiting or authentication required
  • CORS enabled for browser-based applications

API Endpoints

The API provides 6 endpoints for accessing ATP rankings data, player statistics, and historical records.

Get All Available Weeks

GET/api/weeks

Returns a list of all available weeks (dates) for which rankings data is available. Weeks are returned in descending chronological order (newest first).

Response Example

{
  "weeks": [
    "2025-04-21",
    "2025-04-14",
    "2025-04-07",
    "2025-03-31",
    ...
    "1973-09-03",
    "1973-08-27"
  ]
}

Get Rankings for a Specific Week

GET/api/week/{week_date}

Returns the complete ATP rankings for a specific week, including rank, player name, and points for all ranked players.

Path Parameters

ParameterTypeDescription
week_date string, required The date of the week in YYYY-MM-DD format (e.g., "2023-01-02")

Response Example

{
  "week": "2023-01-02",
  "rankings": [
    {
      "rank": "1",
      "name": "Carlos Alcaraz",
      "points": "6,820"
    },
    {
      "rank": "2",
      "name": "Rafael Nadal",
      "points": "6,020"
    },
    {
      "rank": "3",
      "name": "Stefanos Tsitsipas",
      "points": "5,550"
    },
    ...
  ]
}

Error Response (404)

{
  "detail": "Week 2099-01-01 not found"
}

Get Weeks at Number 1 for All Players

GET/api/weeks-at-no1

Returns all players who have held the world number 1 ranking and the number of weeks they spent at #1. Results are sorted by weeks in descending order.

Response Example

[
  {
    "player": "Novak Djokovic",
    "weeks": 428
  },
  {
    "player": "Roger Federer",
    "weeks": 310
  },
  {
    "player": "Pete Sampras",
    "weeks": 286
  },
  {
    "player": "Rafael Nadal",
    "weeks": 209
  },
  ...
]

Search for Players

GET/api/players/search

Search for players in the database by name. Returns a list of player names that match the search query. Useful for autocomplete functionality.

Query Parameters

ParameterTypeDescription
q string, required The search query string (e.g., "federer", "djokovic")
limit integer, optional, default: 10 Maximum number of results to return

Response Example

{
  "players": [
    "Roger Federer",
    "Federer Jr.",
    ...
  ]
}

Get Player Factfile/Statistics

GET/api/player/factfile

Returns comprehensive career statistics for a specific player including career high ranking, maximum points, and weeks spent in various ranking tiers.

Query Parameters

ParameterTypeDescription
player string, required The exact player name (e.g., "Roger Federer", "Rafael Nadal")

Response Example

{
  "player": "Roger Federer",
  "career_high_rank": 1,
  "career_high_date": "2004-02-02",
  "max_points": "15,903",
  "max_points_date": "2012-11-05",
  "weeks_top_100": 1234,
  "weeks_top_10": 890,
  "weeks_at_1": 310
}

Error Response (404)

{
  "detail": "Player Roger Federerr not found"
}

Get Player Career Data for Charts

GET/api/player/career

Returns time-series data of a player's ranking and points history throughout their career. This data is used for generating career progression charts and visualizations.

Query Parameters

ParameterTypeDescription
player string, required The exact player name (e.g., "Rafael Nadal", "Novak Djokovic")

Response Example

{
  "player": "Rafael Nadal",
  "ranking_dates": ["2005-08-08", "2005-08-15", "2005-08-22", ...],
  "rankings": [49, 45, 43, 40, ...],
  "points_dates": ["2005-08-08", "2005-08-15", "2005-08-22", ...],
  "points": [823, 845, 890, 912, ...]
}
Note: The points arrays only include weeks where the player had non-zero points. Ranking arrays include all weeks where the player was in the top 100.

Usage Examples

JavaScript (Fetch API)

// Get all available weeks
fetch('https://atp-rankings-data-visualization.onrender.com/api/weeks')
  .then(response => response.json())
  .then(data => {
    console.log('Total weeks:', data.weeks.length);
    console.log('Latest week:', data.weeks[0]);
  });

// Get rankings for a specific week
fetch('https://atp-rankings-data-visualization.onrender.com/api/week/2023-01-02')
  .then(response => response.json())
  .then(data => {
    console.log('Week:', data.week);
    console.log('Number 1:', data.rankings[0]);
  });

// Get weeks at number 1 statistics
fetch('https://atp-rankings-data-visualization.onrender.com/api/weeks-at-no1')
  .then(response => response.json())
  .then(data => {
    console.log('Total players who reached #1:', data.length);
    console.log('Most weeks at #1:', data[0]);
  });

// Search for players
fetch('https://atp-rankings-data-visualization.onrender.com/api/players/search?q=federer&limit=5')
  .then(response => response.json())
  .then(data => {
    console.log('Found players:', data.players);
  });

// Get player factfile
fetch('https://atp-rankings-data-visualization.onrender.com/api/player/factfile?player=Roger%20Federer')
  .then(response => response.json())
  .then(data => {
    console.log(`${data.player}: Career High #${data.career_high_rank}`);
    console.log(`Weeks at #1: ${data.weeks_at_1}`);
  });

// Get player career data for charts
fetch('https://atp-rankings-data-visualization.onrender.com/api/player/career?player=Rafael%20Nadal')
  .then(response => response.json())
  .then(data => {
    console.log(`Career data points: ${data.rankings.length} weeks`);
    console.log(`Best ranking: #${Math.min(...data.rankings)}`);
  });

Response Format

Content Type

All responses are returned in JSON format with Content-Type: application/json

Status Codes

StatusMeaning
200 OKRequest successful
404 Not FoundWeek not found in database
500 Internal Server ErrorServer error occurred

Data Structure

Week Data Object:

{
  "rank": "string",     // Player's ranking position (e.g., "1", "2", "3")
  "name": "string",     // Player's full name
  "points": "string"    // Points with comma separators or "-" if not available
}

Best Practices

  • Caching: Consider caching responses as historical data rarely changes
  • Error Handling: Always check for 404 errors when requesting specific weeks
  • Date Format: Use YYYY-MM-DD format for week dates (e.g., "2023-01-02")
  • Pagination: The API returns complete datasets - implement client-side pagination if needed
  • Rate Limiting: While there's no enforced rate limit, please be respectful with request frequency

MCP Server (AI Integration)

This API also includes a real Model Context Protocol (MCP) server, implemented with the official MCP Python SDK, speaking JSON-RPC 2.0 over the Streamable HTTP transport. It exposes the same underlying data through proper MCP tools, and can be added directly as a custom connector in Claude.ai or any other MCP-compatible client.

MCP Endpoint

  • Single endpoint: POST /mcp (Streamable HTTP transport — initialize, tools/list, tools/call)

Available Tools

  • search_players(query, limit)
  • get_player_factfile(player)
  • get_player_career(player)
  • get_weeks_at_no1()
  • get_all_weeks()
  • get_week_rankings(week_date)
A legacy set of REST-style endpoints under /mcp/* (e.g. GET /mcp/health, POST /mcp/tools/search_players) remains available for backwards compatibility, but is not a real MCP server and will not work with Claude.ai's custom connector flow — use the /mcp endpoint above instead.

For complete MCP documentation, see the MCP_README.md file.

Support

For issues, questions, or feature requests, please visit the GitHub repository.

Note: This is a free, public API provided as-is. No SLA or uptime guarantees are provided.