ATP Rankings Data Visualization / API

What this project does

The idea behind this project is simple: take decades of ATP rankings data that normally lives in scattered web pages and turn it into something useful, searchable, and programmable.

• Scrapes official ATP rankings and maintains a local database of 2,600+ weeks.
• Lets users browse rankings by week, search for players, and compare careers.
• Exposes a REST API and a Model Context Protocol (MCP) server so AI assistants can answer questions about tennis history.
• Includes CLI tools for generating plots and checking the database from the terminal.

Tech stack

• Backend: Python 3.12, FastAPI, Uvicorn, Pydantic
• Database: SQLite3, with 2,600+ tables from 1973 to present
• Frontend: Jinja2 templates, Chart.js, HTML, and CSS
• Scraping and analysis: BeautifulSoup4, Matplotlib
• Testing and deployment: pytest, Docker, Render

How to run it locally

For full details, see the README in the repository, but the basic flow is:

1. Clone the repository and create a virtual environment.
2. Install dependencies with pip install -r requirements.txt.
3. Run the web app with uvicorn src.main:app --reload.

# start the dev server
uvicorn src.main:app --reload

# update the database with the latest rankings
python scripts/filler.py

# run tests
pytest tests/ -v

Example things you can do

• Look up who was ranked #1 on a specific week.
• Compare ranking history for players like Novak Djokovic and Rafael Nadal.
• See how many weeks different players have spent at world #1.
• Call MCP tools from an AI assistant to ask questions like “show Federer vs Nadal ranking history” without touching the database yourself.

Future ideas

If you have ideas for new tennis statistics, visualizations, or integrations, feel free to open an issue or discussion on GitHub.