📚 API Documentation

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.

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.

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

{
  "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"
    },
    ...
  ]
}

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

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

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

{
  "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
}

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

{
  "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, ...]
}

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)}`);
  });

Python (Requests)

import requests

# Get all available weeks
response = requests.get('https://atp-rankings-data-visualization.onrender.com/api/weeks')
data = response.json()
print(f"Total weeks: {len(data['weeks'])}")

# Get rankings for a specific week
response = requests.get('https://atp-rankings-data-visualization.onrender.com/api/week/2023-01-02')
data = response.json()
print(f"Week: {data['week']}")
print(f"Number 1: {data['rankings'][0]['name']}")

# Get weeks at number 1 statistics
response = requests.get('https://atp-rankings-data-visualization.onrender.com/api/weeks-at-no1')
data = response.json()
print(f"Total players who reached #1: {len(data)}")
print(f"Most weeks at #1: {data[0]['player']} with {data[0]['weeks']} weeks")

# Search for players
response = requests.get('https://atp-rankings-data-visualization.onrender.com/api/players/search', 
                        params={'q': 'federer', 'limit': 5})
data = response.json()
print(f"Found players: {data['players']}")

# Get player factfile
response = requests.get('https://atp-rankings-data-visualization.onrender.com/api/player/factfile', 
                        params={'player': 'Roger Federer'})
data = response.json()
print(f"{data['player']}: Career High #{data['career_high_rank']}")
print(f"Weeks at #1: {data['weeks_at_1']}")

# Get player career data
response = requests.get('https://atp-rankings-data-visualization.onrender.com/api/player/career', 
                        params={'player': 'Rafael Nadal'})
data = response.json()
print(f"Career data points: {len(data['rankings'])} weeks")
print(f"Best ranking: #{min(data['rankings'])}")

cURL

# Get all weeks
curl https://atp-rankings-data-visualization.onrender.com/api/weeks

# Get specific week
curl https://atp-rankings-data-visualization.onrender.com/api/week/2023-01-02

# Get weeks at number 1
curl https://atp-rankings-data-visualization.onrender.com/api/weeks-at-no1

# Search for players
curl "https://atp-rankings-data-visualization.onrender.com/api/players/search?q=federer&limit=5"

# Get player factfile
curl "https://atp-rankings-data-visualization.onrender.com/api/player/factfile?player=Roger%20Federer"

# Get player career data
curl "https://atp-rankings-data-visualization.onrender.com/api/player/career?player=Rafael%20Nadal"

Response Format

Content Type

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

Status Codes

• 200 OK - Request successful
• 404 Not Found - Week not found in database
• 500 Internal Server Error - Server 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 Model Context Protocol (MCP) server for integration with AI assistants. The MCP server provides the same data access through MCP-compliant endpoints.

MCP Endpoints

• Health Check: GET /mcp/health
• Manifest: GET /mcp/manifest
• Search Players: POST /mcp/tools/search_players
• Player Factfile: POST /mcp/tools/get_player_factfile
• Player Career: POST /mcp/tools/get_player_career
• Weeks at #1: GET /mcp/tools/get_weeks_at_no1
• All Weeks: GET /mcp/tools/get_all_weeks
• Week Rankings: POST /mcp/tools/get_week_rankings

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

🆘 Support

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