Project

ATP Rankings Data Visualization / API

A long-term tennis data project where I collect ATP singles rankings going back to 1973, store them in SQLite, and expose them through a FastAPI web app, REST API, CLI tools, and an MCP server for AI assistants.

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 you can actually work with. The project:

• Scrapes official ATP rankings and keeps a local database of 2,600+ weeks.
• Lets you 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 making plots and checking the database from the terminal.

Tech stack

• Backend: Python 3.12, FastAPI, Uvicorn, Pydantic
• Database: SQLite3 (2,600+ tables, 1973–present)
• Frontend: Jinja2 templates, Chart.js, HTML/CSS
• Scraping & analysis: BeautifulSoup4, Matplotlib
• Testing & deployment: pytest, Docker, Render

How to run it locally (summary)

For full details, see the README in the repository, but roughly:

1. Clone the repo 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.

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