# Tennis Scraper — ATP Rankings, Elo & Matches (`datawell/tennis-scraper`) Actor

ATP rankings and Elo ratings, full player match histories with surface, round, tier and score, plus tournament results with field strength. Surfaces and tiers in plain words, not letter codes. No API key. For betting analytics, fantasy sports and sports media.

- **URL**: https://apify.com/datawell/tennis-scraper.md
- **Developed by:** [Finjard Neumeier](https://apify.com/datawell) (community)
- **Categories:** Sports
- **Stats:** 2 total users, 1 monthly users, 100.0% runs succeeded, 0 bookmarks
- **User rating**: No ratings yet

## Pricing

$5.00 / 1,000 results

This Actor is paid per event. You are not charged for the Apify platform usage, but only a fixed price for specific events.

Learn more: https://docs.apify.com/platform/actors/running/actors-in-store#pay-per-event

## What's an Apify Actor?

Actors are web data automations that power AI and operations. They run on the Apify platform to scrape websites, process data, connect APIs, and automate workflows.
In Batch mode, an Actor accepts a well-defined JSON input, performs an action which can take anything from a few seconds to a few hours,
and optionally produces a well-defined JSON output, datasets with results, or files in key-value store.
In Standby mode, an Actor provides a web server which can be used as a website, API, or an MCP server.
Actors are written with capital "A".

## How to integrate an Actor?

If asked about integration, you help developers integrate Actors into their projects.
You adapt to their stack and deliver integrations that are safe, well-documented, and production-ready.
The best way to integrate Actors is as follows.

- **AI agents and MCP clients** — the [Apify MCP server](https://docs.apify.com/integrations/mcp.md) at `https://mcp.apify.com` (remote, streamable HTTP, OAuth on first use).
- **Agentic workflows and local Actor development** — [Agent Skills](https://apify.com/.well-known/agent-skills/index.json) with the [Apify CLI](https://docs.apify.com/cli/docs.md): `npm install -g apify-cli`, then `apify login`.
- **JavaScript/TypeScript projects** — the official [JS/TS client](https://docs.apify.com/api/client/js/docs.md): `npm install apify-client`.
- **Python projects** — the official [Python client](https://docs.apify.com/api/client/python/docs.md): `pip install apify-client`.
- **Any other language** — the [REST API](https://docs.apify.com/api/v2.md).

For usage examples, see the [API](#api) section below.

For more details, see Apify documentation as [Markdown index](https://docs.apify.com/llms.txt) and [Markdown full-text](https://docs.apify.com/llms-full.txt).

# README

## Tennis Rankings, Matches & Tournaments Scraper

Extract ATP rankings, Elo ratings, complete match histories and tournament
results. No API key, no login, no scraping of rendered pages — this reads a
structured JSON source directly.

***

### Why this scraper

**Elo ratings, not just official rankings.** Official points reward showing up;
Elo measures actual strength and predicts matches far better. Both are one
setting apart here.

**Complete match histories.** Every match a player has contested, with surface,
round, tournament tier, score and opponent — filterable by surface, level and
season. That is the shape you need for form analysis and modelling.

**Readable codes.** The source returns `H`, `C`, `G` for surfaces and `G`, `M`,
`A` for tournament levels. This Actor translates them to Hard, Clay, Grass and
Grand Slam, Masters, ATP 500 — so a CSV is usable without a lookup table.

***

### What you can extract

| Mode | What you get |
|---|---|
| **World rankings** | Rank, points, movement since the last update, career-best rank and points — official or Elo |
| **Matches of a player** | Every match with date, tournament, tier, round, surface, opponent, score, and whether your player won |
| **Tournaments** | Draw size, field strength, average Elo of the field, winner, runner-up and final score |
| **Find a player** | Look up the numeric player ID you need for the match mode |

***

### Quick start

1. Start with **Find a player** and search a name — you get the player ID.
2. Switch to **Matches of a player** and paste that ID.
3. Set **Maximum results**, click **Start**, download as CSV or JSON.

For rankings you can skip straight to **World rankings**.

***

### Example inputs

**Top 500 of the current ATP ranking**

```json
{
  "mode": "rankings",
  "maxItems": 500
}
```

**Elo ratings — who is actually playing best**

```json
{
  "mode": "rankings",
  "rankingType": "ELO_RANK",
  "maxItems": 200
}
```

**A player's full clay-court record**

```json
{
  "mode": "playerMatches",
  "playerIds": ["52602"],
  "surface": "C",
  "maxItems": 500
}
```

**Grand Slam matches of several players**

```json
{
  "mode": "playerMatches",
  "playerIds": ["52602", "4742", "3819"],
  "level": "G",
  "maxItems": 1500
}
```

**Every tournament of a season**

```json
{
  "mode": "tournaments",
  "season": "2024",
  "maxItems": 200
}
```

**Look up a player ID**

```json
{
  "mode": "searchPlayers",
  "searchQuery": "Alcaraz"
}
```

***

### Output fields

#### Rankings

| Field | Description |
|---|---|
| `rank` | Current position |
| `name`, `playerId`, `url` | Who, and the ID for the match mode |
| `country`, `countryCode` | Nation represented |
| `points` | Ranking points, or Elo rating in Elo mode |
| `rankChange` | Movement since the last ranking — negative means the player climbed |
| `pointsChange` | Points gained or lost |
| `bestRank`, `bestRankDate`, `bestPoints` | Career highs |
| `rankingType` | Official or Elo |

#### Matches

| Field | Description |
|---|---|
| `date`, `tournament`, `tournamentId` | When and where |
| `level`, `levelCode` | Grand Slam, Masters, ATP 500 … |
| `round` | Final, Semifinal, Round of 16 … |
| `surface`, `indoor` | Hard, Clay, Grass, Carpet, and whether indoors |
| `bestOf`, `score` | Format and final score |
| `winnerName`, `winnerId`, `winnerCountry`, `winnerSeed` | Who won |
| `loserName`, `loserId`, `loserCountry`, `loserSeed` | Who lost |
| `queriedPlayerWon` | Whether the player you asked about won — no name matching needed |
| `hasDetailedStats` | Whether serve and return statistics exist for the match |

#### Tournaments

| Field | Description |
|---|---|
| `name`, `date`, `season`, `url` | Identity |
| `level`, `surface`, `indoor` | Tier and conditions |
| `drawType`, `drawSize`, `playerCount` | Format |
| `participationPercent`, `fieldStrength`, `averageEloRating` | How strong the field really was |
| `winnerName`, `runnerUpName`, `finalScore` | Outcome |

***

### Limits

- **ATP only.** The underlying source covers men's tennis; there is no WTA data.
- **Tournament history ends in 2024.** Rankings and match records go further, but
  the tournament tables have not been extended past that season.
- **Player IDs are internal.** They are not ATP IDs — use the player search mode
  to find them.
- **Live scores are not included.** This is historical and ranking data, not
  in-play coverage.

***

### FAQ

**Do I need an API key?**
No. The source exposes structured JSON publicly.

**What is the difference between official rankings and Elo?**
Official points depend on which tournaments a player entered. Elo is calculated
from results against rated opponents, which makes it a better predictor.

**How do I find a player ID?**
Run the **Find a player** mode with the surname. The `playerId` column is what
the match mode expects.

**Can I get several players at once?**
Yes. Pass multiple IDs; the result budget is split evenly between them.

**What formats can I export?**
CSV, Excel, JSON, XML, or straight from the Apify API.

***

### Legal and responsible use

This Actor reads publicly available sports statistics. Match results and rankings
are factual records, not personal data in the sensitive sense — but player names
are still personal data under GDPR, and you remain responsible for how you use
and republish the output.

# Actor input Schema

## `mode` (type: `string`):

Pick what you want to collect. The fields below apply depending on this choice.

## `rankingType` (type: `string`):

Official rankings follow the tour's points system. Elo ratings measure actual strength and predict matches better.

## `playerIds` (type: `array`):

Numeric player IDs. Use the 'Find a player' mode first to look them up.

## `searchQuery` (type: `string`):

Name or part of a name, e.g. 'Alcaraz'. Used in the player search mode.

## `maxItems` (type: `integer`):

Total number of records to collect. With several players, the budget is split evenly between them.

## `season` (type: `string`):

Restrict to one year, e.g. 2024. Leave empty for all seasons.

## `surface` (type: `string`):

Only matches or tournaments on this surface.

## `level` (type: `string`):

Only matches or tournaments at this level.

## `rankingDate` (type: `string`):

Historical rankings for a specific date, format 2024-06-10. Leave empty for current.

## `requestDelaySeconds` (type: `integer`):

Seconds to wait between calls. Raise this for very large runs.

## Actor input object example

```json
{
  "mode": "rankings",
  "rankingType": "RANK",
  "maxItems": 100,
  "surface": "",
  "level": "",
  "requestDelaySeconds": 0
}
```

# Actor output Schema

## `results` (type: `string`):

Scraped rankings, matches or tournaments. Ranking rows carry points and rank movement; match rows carry both players, surface, round and score.

## `resultsCsv` (type: `string`):

The same rows as a CSV download, ready for Excel or Google Sheets.

# API

You can run this Actor programmatically using our API. Below are code examples in JavaScript, Python, and CLI, as well as the OpenAPI specification and MCP server setup.

## JavaScript example

```javascript
import { ApifyClient } from 'apify-client';

// Initialize the ApifyClient with your Apify API token
// Replace the '<YOUR_API_TOKEN>' with your token
const client = new ApifyClient({
    token: '<YOUR_API_TOKEN>',
});

// Prepare Actor input
const input = {};

// Run the Actor and wait for it to finish
const run = await client.actor("datawell/tennis-scraper").call(input);

// Fetch and print Actor results from the run's dataset (if any)
console.log('Results from dataset');
console.log(`💾 Check your data here: https://console.apify.com/storage/datasets/${run.defaultDatasetId}`);
const { items } = await client.dataset(run.defaultDatasetId).listItems();
items.forEach((item) => {
    console.dir(item);
});

// 📚 Want to learn more 📖? Go to → https://docs.apify.com/api/client/js/docs

```

## Python example

```python
from apify_client import ApifyClient

# Initialize the ApifyClient with your Apify API token
# Replace '<YOUR_API_TOKEN>' with your token.
client = ApifyClient("<YOUR_API_TOKEN>")

# Prepare the Actor input
run_input = {}

# Run the Actor and wait for it to finish
run = client.actor("datawell/tennis-scraper").call(run_input=run_input)

# Fetch and print Actor results from the run's dataset (if there are any)
print("💾 Check your data here: https://console.apify.com/storage/datasets/" + run["defaultDatasetId"])
for item in client.dataset(run["defaultDatasetId"]).iterate_items():
    print(item)

# 📚 Want to learn more 📖? Go to → https://docs.apify.com/api/client/python/docs/quick-start

```

## CLI example

```bash
echo '{}' |
apify call datawell/tennis-scraper --silent --output-dataset

```

## MCP server setup

```json
{
    "mcpServers": {
        "apify": {
            "command": "npx",
            "args": [
                "mcp-remote",
                "https://mcp.apify.com/?tools=datawell/tennis-scraper",
                "--header",
                "Authorization: Bearer <YOUR_API_TOKEN>"
            ]
        }
    }
}

```

## OpenAPI specification

Download the OpenAPI definition: https://api.apify.com/v2/actors/sU7wRR1Bdatz8JWM0/builds/dN9TzZ1mQADn4Yd6V/openapi.json