# Tennis Point-by-Point Scraper — Rally & Match Stats (`sian.agency/tennis-point-by-point-scraper`) Actor

Point-by-point tennis data no other scraper sells — every serve, rally, and break point of a match, in play order, plus the complete match- and set-level statistics table. Find players by name, then export full match records as JSON, CSV, or Excel. No API key.

- **URL**: https://apify.com/sian.agency/tennis-point-by-point-scraper.md
- **Developed by:** [SIÁN OÜ](https://apify.com/sian.agency) (community)
- **Categories:** Sports, Automation, Developer tools
- **Stats:** 204 total users, 36 monthly users, 97.6% runs succeeded, 1 bookmarks
- **User rating**: No ratings yet

## Pricing

from $18.75 / 1,000 match records

This Actor is paid per event. You are not charged for the Apify platform usage, but only a fixed price for specific events.
Since this Actor supports Apify Store discounts, the price gets lower the higher subscription plan you have.

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

## What's an Apify Actor?

An Actor is a serverless cloud program that runs on the Apify platform. It has two run modes.
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.

Apify vocabulary and the platform model are defined once, in the agent quickstart at https://apify.com/agents.md.

## 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.

Do not guess an integration path. Every one of them is in the agent quickstart at https://apify.com/agents.md: the Apify MCP server, Agent Skills with the Apify CLI, the JavaScript and Python clients, the REST API, and the account-free path for an agent with no human to sign in. It also carries the rule on stating cost before the first paid run.

For examples already wired to this Actor's own input schema, see the [API](#api) section below.

Each client library has reference documentation the quickstart does not restate: [JavaScript/TypeScript](https://docs.apify.com/api/client/js/docs.md) (`npm install apify-client`) and [Python](https://docs.apify.com/api/client/python/docs.md) (`pip install apify-client`).

# README

## Tennis Point-by-Point Scraper — Rally & Match Stats 🎾

[![SIÁN Agency Store](https://img.shields.io/badge/Store-SI%C3%81N%20Agency-1AE392)](https://apify.com/sian.agency?fpr=sian) [![Sports Data Scraper](https://img.shields.io/badge/Store-Sports%20Data%20Scraper-1AE392)](https://apify.com/sian.agency/sports-data-scraper?fpr=sian) [![Sports Betting Odds Scraper](https://img.shields.io/badge/Store-Sports%20Betting%20Odds-1AE392)](https://apify.com/sian.agency/sports-betting-odds-scraper?fpr=sian) [![Football API Scraper](https://img.shields.io/badge/Store-Football%20API%20Scraper-1AE392)](https://apify.com/sian.agency/football-api-scraper?fpr=sian)

#### 🎾 **Point by point tennis data** — every serve, rally and break point in play order, plus the full tennis match statistics table

##### Built for the analysts, traders, scouts and developers who model matches rather than read scorelines

***

### 🔎 What is the Tennis Point-by-Point Scraper — and when should you use it?

The **Tennis Point-by-Point Scraper** turns a player name or a tournament name into clean, structured match rows you can filter, export and feed straight into a spreadsheet, database or AI agent. No account, no portal API key, no browser automation to maintain.

**Use it when you need:** point-by-point rally sequences — sets → games → points, in play order, each carrying the server, the receiver and a break-point flag. It also returns the match and set statistics tables (serve, return, break points, shot quality), match metadata (tournament, city, date, both players), and stable player and tournament IDs to build a roster from.

**Use something else when:** you want live odds or in-play prices rather than completed-match rally data — use [Sports Betting Odds Scraper](https://apify.com/sian.agency/sports-betting-odds-scraper?fpr=sian) for that. This Actor covers **tennis only**. For another sport, use [Football API Scraper](https://apify.com/sian.agency/football-api-scraper?fpr=sian) or [Sports Data Scraper](https://apify.com/sian.agency/sports-data-scraper?fpr=sian).

***

### 🤖 Use with AI agents

Already connected to the [Apify MCP server](https://mcp.apify.com)? Just ask for this Actor by name: sian.agency/tennis-point-by-point-scraper

**Your agent can pay for its own runs.** This Actor is eligible for [agentic payments](https://docs.apify.com/platform/actors/publishing/monetize). An agent can discover it, run it and settle the bill over [x402](https://www.x402.org/) (USDC on Base) or [Skyfire](https://www.skyfire.xyz/), with no Apify account or API token of its own. Billing is the same either way: per successful row, never for errors.

Otherwise copy this prompt into Claude, ChatGPT, Cursor or any MCP-enabled assistant:

```text
I want to analyse a tennis player's recent matches using the Apify Actor `sian.agency/tennis-point-by-point-scraper`.

Use it when I need: point-by-point rally data, match and set statistics, match metadata, or stable player and tournament IDs.

Don't use it when: I want live odds or in-play prices — use `sian.agency/sports-betting-odds-scraper` instead. It covers tennis only; for other sports use `sian.agency/football-api-scraper`.

How to call it — pick ONE `operation` per run:
- "discover-players"           takes `search` (a name), returns player IDs
- "discover-tournaments"       takes `search` (event name or city), returns tournament IDs
- "discover-matches"           takes `playerIds`, returns a deduplicated match-ID list (not billed)
- "discover-tournament-matches" takes `tournamentIds`, returns every match ID in the draw (not billed)
- "scrape-matches"             takes `playerIds`, returns full match records
- "scrape-match-ids"           takes `matchRequests`, returns full match records for IDs I already have

Start with this input:
{
  "operation": "scrape-matches",
  "playerIds": ["feca401d-e9c2-4638-93b0-878fdb9aea74"],
  "maxMatchesPerPlayer": 5,
  "maxTotalMatches": 20,
  "matchFormat": "singles",
  "includePoints": true,
  "includeStats": true
}

Ask me which player or tournament I care about, then run the Actor and summarise the results as a table.
```

**Things you can ask your agent for:**

- *"Find every Bratislava Open match on file and give me the break-point conversion rate for each player."*
- *"Pull Dinev's last ten singles matches and tell me how his first-serve percentage moves between sets."*
- *"Build me a CSV of every point in this match, with the server and whether it was a break point."*

Machine-readable API, MCP config and OpenAPI definition for this Actor are published at [apify.com/sian.agency/tennis-point-by-point-scraper.md](https://apify.com/sian.agency/tennis-point-by-point-scraper.md).

***

### 📋 Overview

**Serve, rally, break, repeat.** This Actor returns the whole match: player and tournament directories, match metadata, every point of every game in play order, and the complete match- and set-level statistics table. All of it lands as clean, structured rows you can analyse in seconds.

**What you get:**

- 🎯 **Point-by-point depth**: every serve, rally, and break point, in order, ready for modeling
- 🏆 **Whole tournaments**: search an event by name or city, then collect every match in the draw
- ⚡ **Two clicks to data**: find a player or a tournament, then pull the matches — no API key, no login
- 🛡️ **Controlled bulk retrieval**: explicit match limits, per-match failure isolation, and resumable two-stage jobs
- 💎 **Full statistics table**: serve, return, break points, plus performance and shot-quality ratings, at match and set level
- 🎾 **Singles-only mode**: filter out doubles before parsing — and never pay for the rows you filtered
- 🌐 **Proxies included**: nothing to configure, nothing extra to pay — we route every request through our own residential network
- ✨ **Export anywhere**: JSON, CSV, or Excel, or straight from the API

***

### ✨ Features

- 🔎 **Player Directory Search**: find any player by name and get a stable ID
- 🏆 **Tournament Directory Search**: find any event by name or host city, then pull its whole draw
- 🎾 **Point-by-Point Data**: sets → games → points, in play order
- 📊 **Match & Set Statistics**: serve/return/break-point rows plus shot-quality ratings
- 🏟️ **Rich Match Metadata**: tournament, location, date, and both players
- 👥 **Multi-Player Runs**: scrape many players at once — shared matches are fetched only once
- 🧭 **Two-Stage Actor Operations**: discover unique match IDs first, then scrape bounded detail batches
- 🔌 **Stable Retrieval Contract**: production clients can plan, deduplicate, and resume outside the Actor
- 🎛️ **Toggle the Payload**: include or skip points/statistics per run
- 📁 **Clean Structured Output**: one tidy dataset per run, ready for analysis
- 🔑 **No API Key Required**: just add input and run

***

### 🎬 Quick Start

Scrape a player's matches — points, rallies and statistics — in one call.

```bash
curl -X POST "https://api.apify.com/v2/acts/sian.agency~tennis-point-by-point-scraper/runs?token=YOUR_TOKEN" \
-H 'Content-Type: application/json' \
-d '{"operation": "scrape-matches", "playerIds": ["feca401d-e9c2-4638-93b0-878fdb9aea74"], "maxMatchesPerPlayer": 5}'
```

Don't have a player ID yet? Look one up first:

```bash
curl -X POST "https://api.apify.com/v2/acts/sian.agency~tennis-point-by-point-scraper/runs?token=YOUR_TOKEN" \
-H 'Content-Type: application/json' \
-d '{"operation": "discover-players", "search": "Dinev"}'
```

Want a whole event instead of one player? Find the tournament, then take its draw:

```bash
curl -X POST "https://api.apify.com/v2/acts/sian.agency~tennis-point-by-point-scraper/runs?token=YOUR_TOKEN" \
-H 'Content-Type: application/json' \
-d '{"operation": "discover-tournaments", "search": "Stuttgart"}'
```

***

### 🚀 Getting Started (3 Simple Steps)

#### Step 1: Hit Start

`scrape-matches` is the default operation and a player is already prefilled, so a first run returns real matches with full point-by-point data for a few cents. No setup at all.

#### Step 2: Point it at your own players

Switch to `discover-players`, search a name, and copy the `playerId` from the results into `playerIds`. Then switch back to `scrape-matches`.

> ⚠️ Leaving `search` empty returns the **entire directory — about 2,600 players, billed per row.** It is capped at `maxPlayers` (default 100), but keep a name in there unless you deliberately want a big slice.

**Want a whole event instead?** Run `discover-tournaments` to find the tournament ID, then `discover-tournament-matches` to collect every match in the draw, then feed those IDs to `scrape-match-ids`. The match-list step is not billed.

#### Step 3: Export your data

Download the dataset as JSON, CSV, or Excel — or pull it straight from the Apify API.

**That's it! In minutes, you'll have:**

- A searchable directory of players with stable IDs
- Full match records with point-by-point data
- Match and set statistics ready for analysis

***

### 📥 Input Configuration

| Field | Type | Required | Description |
|-------|------|----------|-------------|
| operation | string | Yes | `discover-players`, `discover-tournaments`, `discover-matches`, `discover-tournament-matches`, `scrape-matches`, or `scrape-match-ids` |
| search | string | No | Filter the player or tournament directory by name, city, or ID (discover only) |
| playerIds | array | No | Player IDs for `discover-matches` or `scrape-matches` |
| tournamentIds | array | No | Up to 500 tournament IDs for `discover-tournament-matches` |
| matchRequests | array | No | Up to 250 `{matchId, requestedPlayerIds, requestedTournamentIds}` objects for `scrape-match-ids` |
| maxPlayers | integer | No | Hard ceiling on player rows from `discover-players`; default `100` |
| maxTournaments | integer | No | Hard ceiling on tournament rows from `discover-tournaments`; default `100` |
| maxMatchesPerPlayer | integer | No | Matches per player; default `5`, `0` = all |
| maxMatchesPerTournament | integer | No | Matches per tournament draw; default `0` = all |
| maxTotalMatches | integer | No | Hard ceiling on billed matches per run after deduplication; default `20` |
| includePoints | boolean | No | Include nested point-by-point data (default true) |
| includeStats | boolean | No | Include match and set statistics (default true) |
| matchFormat | string | No | `all` (default) or `singles`; singles mode excludes doubles before point/stat parsing |

**Find players:**

```json
{
  "operation": "discover-players",
  "search": "Dinev"
}
```

**Scrape matches:**

```json
{
  "operation": "scrape-matches",
  "playerIds": ["feca401d-e9c2-4638-93b0-878fdb9aea74"],
  "maxMatchesPerPlayer": 10,
  "maxTotalMatches": 50,
  "matchFormat": "singles",
  "includePoints": true,
  "includeStats": true
}
```

**Build a globally deduplicated match plan:**

```json
{
  "operation": "discover-matches",
  "playerIds": ["feca401d-e9c2-4638-93b0-878fdb9aea74"],
  "maxMatchesPerPlayer": 25,
  "maxTotalMatches": 5000
}
```

**Find tournaments:**

```json
{
  "operation": "discover-tournaments",
  "search": "Berlin"
}
```

**Build a match plan for a whole tournament draw:**

```json
{
  "operation": "discover-tournament-matches",
  "tournamentIds": ["33333333-3333-4333-8333-333333333333"],
  "maxMatchesPerTournament": 0,
  "maxTotalMatches": 5000
}
```

**Scrape explicit match IDs:**

```json
{
  "operation": "scrape-match-ids",
  "matchRequests": [
    {
      "matchId": "c292a56a-5fbe-464e-a768-0fc26f483be2",
      "requestedPlayerIds": ["feca401d-e9c2-4638-93b0-878fdb9aea74"]
    }
  ],
  "matchFormat": "singles"
}
```

***

### 📤 Output

Results are saved to the Apify dataset. Runs return **player**, **tournament**, **match-reference**, **match**, or **match-exclusion** records. In singles mode, doubles produce lightweight exclusions after metadata classification and before point/stat parsing. Unknown formats are fully scraped to avoid accidental data loss. Structured per-item failures are stored in the run's `FAILURES` key-value record.

| Field | Type | Description |
|-------|------|-------------|
| recordType | string | `player`, `tournament`, `match-reference`, `match`, or `match-exclusion` |
| playerId / fullName | string | Player ID and name (player records) |
| tournamentId / title / city | string | Tournament ID, event name, and host city (tournament records) |
| requestedPlayerIds | array | Requested players that led to a match reference or record |
| requestedTournamentIds | array | Requested tournaments that led to a match reference or record |
| matchId / title | string | Match ID and title (match records) |
| matchFormat | string | `singles`, `doubles`, or `unknown` |
| exclusionReason | string | Why a `match-exclusion` record was not fully parsed |
| tournament / location | string | Event name and place |
| completedAt | string | When the match finished |
| completedAtUtc | string | The same completion time as a precise UTC timestamp |
| pointCount | number | Total points in the match |
| playerIds | array | Both players resolved from point data |
| sets | array | Nested sets → games → points |
| stats | array | Match- and set-level statistics rows |

**Example (match record — real output, trimmed):**

```json
{
  "recordType": "match",
  "matchId": "313b5434-cffc-4938-804c-e6edeec28e8e",
  "title": "Ivanov vs Dinev | 2026#3007#QS008 | Tennis Results",
  "tournament": "LEXUS NOTTINGHAM CHALLENGER 3",
  "matchFormat": "singles",
  "pointCount": 146,
  "playerIds": ["7626aa33-...", "feca401d-..."],
  "sets": [
    { "setNumber": 1, "games": [{ "gameNumber": 1, "points": [
      {
        "pointNumber": 1,
        "setNumber": 1,
        "gameNumber": 1,
        "winner": "teamA",
        "teamServing": "teamA",
        "playerServing": "7626aa33-7f05-436e-a24a-282a666310f8",
        "playerReceiving": "feca401d-e9c2-4638-93b0-878fdb9aea74",
        "rally": [
          { "sequence": 1, "type": "SERVE" },
          { "sequence": 2, "type": "ACE" },
          { "sequence": 3, "type": "POINT_COMPLETE" }
        ],
        "pointBreakdown": {
          "outcome": "winner", "serve": "ACE", "totalShots": "1",
          "winningShotType": "serve", "errorType": null, "situation": "serving"
        },
        "ace": true, "isBreakPoint": false, "isDeuce": false,
        "streak": { "owner": "teamA", "count": 1 },
        "time": "2026-07-06T13:27:53.474Z"
      }
    ] }] }
  ],
  "stats": [
    { "scope": "match", "category": "Points", "metric": "Total Points Won", "teamAValue": "81", "teamBValue": "65" },
    { "scope": "set", "setNumber": "1", "category": "Service", "metric": "Break Points Saved", "teamAValue": "4", "teamBValue": "3" }
  ]
}
```

That single match carried **146 points across 3 sets and 84 statistic rows** — one billed record.

***

### 💼 Use Cases & Examples

#### 1. Tennis Analytics & Modeling

**Data scientists building serve/return and momentum models.**
**Input:** Player IDs of the players you follow. **Output:** Point-by-point sequences + statistics. **Use:** Train win-probability and momentum models on real rally data.

#### 2. Betting & Trading Research

**Traders backtesting tennis markets.**
**Input:** A roster of players. **Output:** Historical match results with detailed in-match stats. **Use:** Validate edges and study live-trading spots.

#### 3. Player Scouting & Coaching

**Coaches and scouts preparing for opponents.**
**Input:** A player's ID. **Output:** Full match history with serve/return breakdowns. **Use:** Build opponent scouting reports and head-to-head views.

#### 4. Sports Media & Content

**Journalists and creators covering tournaments.**
**Input:** Search a player by name. **Output:** Match metadata + stats. **Use:** Fact-check stories and generate match recaps.

#### 5. Data Products & Feeds

**Developers powering apps and dashboards.**
**Input:** Scheduled runs over a player list. **Output:** Clean JSON match records. **Use:** Feed a live tennis stats product without maintaining a scraper.

#### 6. Fantasy & Community Tools

**Fantasy platforms and stat communities.**
**Input:** A directory of players. **Output:** Match and point data. **Use:** Power fantasy scoring and leaderboards.

#### 7. Tournament-Wide Analysis

**Researchers studying a single event end to end.**
**Input:** A tournament ID from `discover-tournaments`. **Output:** Every match in the draw, deduplicated. **Use:** Compare surface effects, measure how a draw played out, or build an event archive without listing a single player.

***

### 🔗 Integration Examples

#### JavaScript/Node.js

```javascript
import { ApifyClient } from 'apify-client';
const client = new ApifyClient({ token: 'YOUR_TOKEN' });

const run = await client.actor('sian.agency/tennis-point-by-point-scraper').call({
  operation: 'scrape-matches',
  playerIds: ['feca401d-e9c2-4638-93b0-878fdb9aea74'],
  maxMatchesPerPlayer: 10
});

const { items } = await client.dataset(run.defaultDatasetId).listItems();
console.log(items[0]);
```

#### Python

```python
from apify_client import ApifyClient
client = ApifyClient('YOUR_TOKEN')

run = client.actor('sian.agency/tennis-point-by-point-scraper').call(
    run_input={
        'operation': 'scrape-matches',
        'playerIds': ['feca401d-e9c2-4638-93b0-878fdb9aea74'],
        'maxMatchesPerPlayer': 10,
    }
)

for item in client.dataset(run['defaultDatasetId']).iterate_items():
    print(item)
```

#### cURL

```bash
curl -X POST 'https://api.apify.com/v2/acts/sian.agency~tennis-point-by-point-scraper/runs?token=YOUR_TOKEN' \
-H 'Content-Type: application/json' \
-d '{"operation": "discover-players", "search": "Dinev"}'
```

#### Automation Workflows (N8N / Zapier / Make)

1. **Trigger**: Schedule or webhook
2. **HTTP Request**: Call the actor API
3. **Process**: Handle JSON results
4. **Action**: Save, notify, or transform

***

### 📊 Performance & Pricing

**You pay per record, and only for records you actually receive:**

| Event | What it is |
|---|---|
| **Match record** | One complete match — metadata, every point of every game, and the full match & set statistics table |
| **Player record** | One player-directory entry (ID, name, results link) |
| **Tournament record** | One tournament-directory entry (ID, event name, host city, results link) |

A match record is an entire match: a typical singles match carries 100–200+ points plus dozens of statistic rows in a single billed row. **Doubles excluded by `matchFormat: "singles"` are never charged, and neither are the match-plan rows from `discover-matches` or `discover-tournament-matches`** — you only pay for data you asked for and received.

**Proxies are on us.** There is nothing to configure and nothing extra to pay: every request goes through our own residential proxy network, included in the per-record price. You will not find a proxy field in the input — you never need one.

#### Free trial vs paid

| | Free plan | Paid plan |
|---|---|---|
| Players per `discover-players` run | 25 | uncapped |
| Tournaments per `discover-tournaments` run | 25 | uncapped |
| Matches per player | 5 | uncapped |
| Matches per run | 5 | up to 10,000 |

The free plan is a real trial, not a demo: same fields, same rally depth, same statistics. Every cap lifts on any paid Apify plan.

**Your first run is cheap by design.** The defaults scrape a small sample — 5 matches per player, 20 per run — so you can inspect the data shape for pennies before scaling up. `maxTotalMatches` is a hard ceiling: a run can never bill more matches than that number. Apify compute and storage are billed by Apify under the account that starts the run.

### 🏗️ Large-Scale Retrieval

For jobs bigger than one run, use the two-stage contract. Call `discover-matches` with your full player roster — or `discover-tournament-matches` with a list of tournaments — to get a globally deduplicated match plan. Every unique match ID appears once, no matter how many of your players or events it belongs to. Then submit those IDs to `scrape-match-ids` in bounded batches of up to 250.

Because the plan is stable and deduplicated, your own client can checkpoint it, resume after an interruption, and re-run only the match IDs it is still missing.

***

### ❓ Frequently Asked Questions

**Q: How do I get a player's matches?**
A: Run `discover-players` first to get the player's ID, then pass that ID to `scrape-matches`.

**Q: Can I scrape a whole tournament?**
A: Yes. Run `discover-tournaments` to find the event's ID, `discover-tournament-matches` to collect every match in the draw, then `scrape-match-ids` to pull them. Building the match list is not billed.

**Q: What are the free-plan limits?**
A: 25 players or tournaments per discovery run, 5 matches per player, and 5 matches per run, up to 30 runs a day. The fields and rally depth are identical to the paid plan — every cap lifts on any paid Apify plan.

**Q: Can I call this Actor from the API on a free plan?**
A: Run it from the Apify Console or through an MCP client for free. Calling the REST API directly needs any paid Apify plan — that keeps the shared proxy pool healthy for everyone. A free-plan API run finishes cleanly and tells you this, it does not error out.

**Q: How many matches can I scrape?**
A: Defaults are deliberately small — 5 per player, 20 per run — so a first run costs pennies. Raise `maxTotalMatches` up to 10,000 for a planned job, or split larger ones with `discover-matches` → `scrape-match-ids`.

**Q: Am I charged for doubles I filtered out?**
A: No. In `singles` mode, doubles are classified from match metadata and skipped before any point or statistics parsing, and those exclusion rows are not billed.

**Q: Can I get every point of a match?**
A: Yes — with `includePoints` enabled, each match returns its sets, games, and points in order.

**Q: What statistics are included?**
A: Serve, return, and break-point stats plus performance and shot-quality ratings, at both match and set level.

**Q: What output formats are available?**
A: JSON, JSONL, CSV, and Excel — export directly from the Apify dataset.

**Q: Do I need an account or API key for the source?**
A: No. Just add your input and run the Actor.

**Q: Do I need to set up a proxy?**
A: No — and there is no proxy field to fill in. Every request is routed through our own residential proxy network at no extra cost to you.

**Q: Which players and tournaments are covered?**
A: The player directory carries thousands of players, and match coverage is strongest on ATP Challenger and ITF-level events. Not every player in the directory has matches on file — in a 31-player sample, 19 had match listings (up to 20 matches each). Run `discover-players` and then `discover-matches` to see exactly what is available for your roster before committing to a large scrape; `discover-matches` plan rows are not charged.

***

### 🐛 Troubleshooting

**No matches returned for a player**

- Double-check the player ID from `discover-players`
- The player genuinely may have no matches on file — the directory lists more players than have match records. Use `discover-matches` (unbilled) to check a roster before scraping it.

**Run stopped at the total-match limit**

- Increase `maxTotalMatches` deliberately after reviewing the expected number of billed match records

**Empty player search**

- Broaden your `search` term, or leave it empty to return the full directory

***

### ⚖️ Is it legal to scrape data?

Our actors are ethical and do not extract any private user data, such as email addresses, gender, or location. They only extract what the user has chosen to share publicly. We therefore believe that our actors, when used for ethical purposes by Apify users, are safe.

However, you should be aware that your results could contain personal data. Personal data is protected by the **GDPR** in the European Union and by other regulations around the world. You should not scrape personal data unless you have a legitimate reason to do so. If you're unsure whether your reason is legitimate, consult your lawyers.

You can also read Apify's blog post on the [legality of web scraping](https://blog.apify.com/is-web-scraping-legal/).

***

### 🤝 Support

**Join our active support community**

- For issues or questions, open an issue in the actor's repository
- Check [SIÁN Agency Store](https://apify.com/sian.agency?fpr=sian) for more automation tools
- 📧 <apify@sian-agency.online>

***

**Built by [SIÁN Agency](https://www.sian-agency.online)** | **[More Tools](https://apify.com/sian.agency?fpr=sian)**

# Changelog

This Actor's version history is a separate document: https://apify.com/sian.agency/tennis-point-by-point-scraper/changelog.md

# Actor input Schema

## `operation` (type: `string`):

🎯 **Pick one operation per run.** Each run produces one clean dataset matching the chosen mode.

- **🎾 Scrape a player's matches** — the main event. Full matches: every point in play order plus the complete statistics table
- **🔎 Find players** — look up a player by name to get their ID
- **🏆 Find tournaments** — look up a tournament by name or city to get its ID
- **📋 Build a match list** — collect unique match IDs for a roster without scraping them yet (not billed)
- **🏆 Build a tournament match list** — collect every match ID from a tournament's draw without scraping them yet (not billed)
- **📋 Scrape specific matches** — scrape match IDs you already have

💡 **Just hit Start.** A player is already filled in below, so a default run returns real matches straight away.

🔎 **Scraping someone else?** Switch to `Find players`, search their name, copy the `playerId` from the results into 🎾 Player IDs, then switch back here.

🧭 **For big jobs:** build a match list first — it deduplicates matches shared between players so you never pay for the same match twice — then feed the IDs to `Scrape specific matches` in batches.

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

🎾 **Required for `Scrape a player's matches` and `Build a match list`.** Ignored by the other operations.

Paste one or more player IDs from your `Find players` results. Add as many as you like — up to 500 — and a match shared by two of them is fetched, and billed, only once.

💡 Not every player in the directory has matches on file; coverage is strongest on ATP Challenger and ITF events. Run `Build a match list` first to see what exists for your roster without being billed for it.

## `search` (type: `string`):

🔎 **Used by `Find players` and `Find tournaments`.** Ignored by every other operation.

For players, type part of a name. For tournaments, type part of the event name or its host city. Matching is partial and case-insensitive, so `dinev` and `Dinev` both work.

⚠️ **Leave this empty and you get the whole directory — about 2,600 players, billed per row.** Keep a name here unless you deliberately want the full list.

💡 Copy the `playerId` from your results into 🎾 Player IDs.

## `maxPlayers` (type: `integer`):

The hard ceiling on player rows returned by `Find players`.

This is your spend guard: every player row is billed, and an empty name field matches the whole directory of roughly 2,600 players. Raise it when you genuinely want a bigger slice — up to 10,000.

## `tournamentIds` (type: `array`):

🏆 **Required for `Build a tournament match list`.** Ignored by every other operation.

Paste one or more tournament IDs from your `Find tournaments` results — up to 500. Every match in each draw is collected, and a match shared by two tournaments is listed only once.

💡 The resulting match IDs are not scraped yet. Feed them to `Scrape specific matches` when you are ready to pull the point-by-point data.

## `maxTournaments` (type: `integer`):

The hard ceiling on tournament rows returned by `Find tournaments`.

This is your spend guard: an empty name field matches the entire tournament directory. Raise it when you genuinely want a bigger slice — up to 10,000.

## `matchRequests` (type: `array`):

📋 **Required for `Scrape specific matches`.** Ignored by every other operation — most users never touch this field.

Use it only when you already hold match IDs, typically from a `Build a match list` run, and want to scrape them in controlled batches. Up to 250 per run.

Each entry takes a `matchId`, and optionally the players it belongs to:

```json
[{ "matchId": "313b5434-cffc-4938-804c-e6edeec28e8e" }]
```

💡 **Scraping one player?** Ignore this and use `Scrape a player's matches` instead.

## `maxMatchesPerPlayer` (type: `integer`):

Cap how many matches to take from each player's history. Set `0` to take every match on file.

Starts at `5` so your first run is quick and cheap. Raise it once you have seen the data — there is no upper limit beyond the total cap below.

## `maxMatchesPerTournament` (type: `integer`):

Cap how many matches to take from each tournament's draw when running `Build a tournament match list`. Set `0` to take every match in the draw.

Only this operation reads it — a player scrape uses `Matches per player` above.

## `maxTotalMatches` (type: `integer`):

The hard ceiling on matches scraped in one run, applied after duplicates are removed.

This is your spend guard: a run can never bill more matches than this number. Raise it deliberately for a planned bulk retrieval — up to 10,000.

## `matchFormat` (type: `string`):

Choose `Singles only` to skip doubles matches.

Doubles are identified from match metadata and dropped before any point or statistics parsing, so **you are never billed for a match this filter removes**.

## `includePoints` (type: `boolean`):

Keep this on for the rally-level data — sets, games, and every point in play order, each with server, receiver, shot sequence, and break-point flags.

Turn it off for a lighter payload when you only want scorelines and statistics. The price per match is the same either way.

## `includeStats` (type: `boolean`):

Keep this on for the full statistics table — serve, return, break points, and shot-quality ratings, at both match and set level. A typical match carries 40–90 statistic rows.

Turn it off for a lighter payload. The price per match is the same either way.

## Actor input object example

```json
{
  "operation": "scrape-matches",
  "playerIds": [
    "feca401d-e9c2-4638-93b0-878fdb9aea74"
  ],
  "search": "Dinev",
  "maxPlayers": 100,
  "tournamentIds": [
    "33333333-3333-4333-8333-333333333333"
  ],
  "maxTournaments": 100,
  "matchRequests": [],
  "maxMatchesPerPlayer": 5,
  "maxMatchesPerTournament": 0,
  "maxTotalMatches": 20,
  "matchFormat": "all",
  "includePoints": true,
  "includeStats": true
}
```

# Actor output Schema

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

No description

## `summary` (type: `string`):

No description

## `failures` (type: `string`):

No description

# 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 = {
    "playerIds": [
        "feca401d-e9c2-4638-93b0-878fdb9aea74"
    ],
    "search": "Dinev"
};

// Run the Actor and wait for it to finish
const run = await client.actor("sian.agency/tennis-point-by-point-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 = {
    "playerIds": ["feca401d-e9c2-4638-93b0-878fdb9aea74"],
    "search": "Dinev",
}

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

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

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

```

## CLI example

```bash
echo '{
  "playerIds": [
    "feca401d-e9c2-4638-93b0-878fdb9aea74"
  ],
  "search": "Dinev"
}' |
apify call sian.agency/tennis-point-by-point-scraper --silent --output-dataset

```

## MCP server setup

```json
{
    "mcpServers": {
        "apify": {
            "type": "http",
            "url": "https://mcp.apify.com/?tools=fetch-actor-details,sian.agency/tennis-point-by-point-scraper"
        }
    }
}
```

The hosted server signs you in with OAuth on first connect, so no API token belongs in this config. Clients without OAuth support can send an `Authorization: Bearer <APIFY_API_TOKEN>` header instead, using a token from API & Integrations in Apify Console (https://console.apify.com/settings/integrations).

## OpenAPI specification

Download the OpenAPI definition: https://api.apify.com/v2/actors/KDNVbiwolJR2hwC9E/builds/5Ur31gT8eiZbm2CD4/openapi.json