# TennisExplorer Results & Bookmaker Odds (`automatic/tennis-results-odds`) Actor

Collect dated ATP, WTA, Challenger and ITF match results with set scores and available bookmaker opening and last odds. Inclusive date ranges, fixtures, ESPN cross-checks and saved new-results feeds.

- **URL**: https://apify.com/automatic/tennis-results-odds.md
- **Developed by:** [Philip Kirkbride](https://apify.com/automatic) (community)
- **Categories:** Sports
- **Features:** Limited permissions
- **Stats:** 2 total users, 1 monthly users, 100.0% runs succeeded, 0 bookmarks
- **User rating**: No ratings yet

## Pricing

from $4.00 / 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.

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

## TennisExplorer Results & Bookmaker Odds

Collect tennis results and available bookmaker opening and last quoted odds from
TennisExplorer, with ESPN cross-checks where a match can be identified. Export
one record per match, including both players or doubles pairs, set scores,
tiebreak points, tournament context and source links.

### Use cases

- Build model training data that pairs tennis outcomes with available odds.
- Supply dated ATP, WTA, Challenger and ITF results feeds to an app or newsroom.
- Backtest against last quoted pre-match odds, keeping their time and coverage limits visible.
- Schedule alerts for new results and corrected scores without charging again for unchanged matches.

### Also available

The sports odds and data suite: pick the job.

| Actor | Use when |
|---|---|
| **Tennis Results & Odds (this Actor)** | ATP and WTA results with bookmaker odds |
| [ESPN Scores & Odds](https://apify.com/automatic/espn-sports) | Scores, schedules and ESPN's betting lines |
| [Pinnacle Odds](https://apify.com/automatic/pinnacle-odds) | Sharp lines with stake limits |
| [US Sportsbook Odds](https://apify.com/automatic/actionnetwork-odds) | DraftKings, FanDuel and BetMGM lines side by side |
| [UFC Fight Data](https://apify.com/automatic/ufc-fight-data) | Fighters, cards, results and moneylines |

### Quick start

The Console prefill requests yesterday's ATP and WTA singles, capped at 20:

```json
{"tours":["ATP","WTA"],"matchTypes":["singles"],"lastDays":1,"includeOdds":true,"includeFixtures":false,"enrichWithEspn":true,"onlyNewSinceLastRun":false,"maxResults":20}
```

An empty input (`{}`) returns an announced sample of up to 20 completed ATP/WTA
singles from yesterday. If that day has none, it checks up to seven earlier days
and says which dates it tried. The status starts with “Sample run (” and
`OUTPUT.sampleRun` is `true`. Yesterday, relative dates and date boundaries use
Europe/Prague. Explicit empty lists, blank values and unknown fields end the run as
`no_results` with a message naming the field; one unusable or duplicate list
entry is skipped into `OUTPUT.skippedSearches` and the rest still runs.

### Input

Omit optional fields to use the behavior below. Illustrative form values do not
silently override your input.

| Field | Omitted behavior | Accepted values and purpose |
| --- | --- | --- |
| `tours` | ATP and WTA | Nonempty list: `ATP`, `WTA`, `Challenger`, `ITF men`, `ITF women`. |
| `matchTypes` | Singles | Nonempty list: `singles`, `doubles`. |
| `dateFrom` | Yesterday, unless `lastDays` is given | Inclusive `YYYY-MM-DD`. Supply both dates. Earliest accepted date: 2000-01-01; coverage varies. |
| `dateTo` | Same as above | Inclusive `YYYY-MM-DD`, at most 14 calendar days per range. Today/future dates require `includeFixtures: true`; at most 7 days ahead. |
| `lastDays` | One completed day | Integer 1–14, ending yesterday. Cannot combine with either date field. |
| `players` | All listed players | Nonempty list of up to 50 name tokens or native player slugs (1–200 characters each; Latin names or native IDs). Use surnames, for example `Noskova`; full given names may be abbreviated in listings. Any listed player can match a doubles pair. |
| `tournaments` | All listed tournaments | Nonempty list of up to 50 name substrings or native tournament edition IDs (1–200 characters each). |
| `includeOdds` | `true` | Include each listed book's available opening and last prices, plus best/average last prices. |
| `includeFixtures` | `false` | Include scheduled matches for today/future dates. Past dates collect results. Underway matches are excluded. Cannot combine with saved-state mode. |
| `enrichWithEspn` | `true` | Cross-check ATP/WTA results and add native athlete IDs, court, venue, start time and `timeValid` where matched. |
| `maxResults` | `20` | Integer 1–1,000. A request or data limit may stop the run sooner. In feed mode this caps new/changed deliveries, including matches beyond previously delivered ones. |
| `onlyNewSinceLastRun` | `false` | Deliver unseen match keys and changes to result status, winner or set scores. First run is a labelled baseline. |
| `stateKey` | Derived from your filters | Feed history name, 1–64 letters, digits or `! _ . ' ( ) -`. Requires feed mode. Change it to start a new baseline. |
| `proxyConfiguration` | None | Optional connection configuration. Usually leave omitted. |

### Date ranges and saved results feeds

An inclusive range runs as one job, rather than requiring one run per date:

```json
{"tours":["ATP","WTA"],"dateFrom":"2026-11-08","dateTo":"2026-11-10","maxResults":6}
```

Small capped ranges alternate dates and tours so one busy day does not consume
the whole preview. Check `OUTPUT.byDay`, `sourceMatchesInScope` and `capsReached`
before treating a capped export as complete. Split large backfills into shorter
ranges. All matches retain the original listed date and time alongside UTC.

For a saved results feed:

```json
{"tours":["ATP","WTA"],"dateFrom":"2026-11-10","dateTo":"2026-11-10","players":["Noskova"],"onlyNewSinceLastRun":true,"stateKey":"tennis-live-check","maxResults":2}
```

Run the same input twice: the first delivery is marked `change.kind: baseline`;
unchanged results produce zero rows on the next run. For a recurring schedule,
replace the date pair with `lastDays` and retain an overlap of several days for
late results. Keep filters and `stateKey` consistent, and run only one job at a
time for each key. Overlapping jobs on different platform containers are not
protected by a distributed lock; configure schedules and callers to serialize
them. Local runs sharing a storage directory reject an overlapping key. Changed
results include a revision and previous status.
Undelivered records remain eligible for the next run, including after a charge
limit. Rows and their delivery acknowledgements are saved as they are collected.
Fixture exports are available in ordinary runs; saved feeds accept results only,
so a scheduled fixture and its final result cannot incur two feed charges.
Missing matches in a partial run never erase saved history.

This is a results feed, not an odds-change alert service. Once a result is
unchanged, its detailed odds are not fetched again. Corrections made only to
bookmaker history or player/tournament metadata do not trigger another delivery.
A ledger holds at most 20,000 match identities and 8 MB; use a new key for a new season or
backfill partition. No-change runs still have the disclosed run-start charge.

### More examples

A named player:

```json
{"players":["Noskova"],"dateFrom":"2026-11-10","dateTo":"2026-11-10","maxResults":2}
```

Upcoming matches with odds:

```json
{"tours":["WTA"],"includeFixtures":true,"dateFrom":"2026-11-12","dateTo":"2026-11-12","maxResults":2}
```

A lower tier:

```json
{"tours":["Challenger"],"dateFrom":"2026-11-10","dateTo":"2026-11-10","maxResults":2}
```

These dated examples were run on November 11, 2026. For new fixtures, change the
dates to the upcoming dates you need.

### Output

The default dataset contains one match per row:

- `matchKey`, `nativeId`, `schemaVersion`, `tour`, `date`, `matchType` and `round` identify the observation.
- `tournament` includes its listed name and native edition ID, tier/category, surface, indoor/outdoor, country, monetary prize total and source link when available. Men's Futures headings may remain generic when a more specific event is not listed.
- `scheduledStart` is UTC with `startTimeBasis` preserving the local date/time, timezone and determination. This is a listed scheduled time, not a claim about the actual first serve.
- `sides` preserves the two sides' order, native IDs, members, names, seeds, country and rankings where available. Profile rankings are current observations, explicitly labelled, not historical match-date rankings.
- `status` is `final`, `retired`, `walkover`, `cancelled` or `scheduled`; `statusNative` preserves the source totals and how the state was determined. `winner` is side index 0 or 1, or null. Nonstandard outcomes are separate from ordinary finals.
- `sets` contains games and published tiebreak points for each side. `duration` is null where not listed. Missing tiebreak points stay null, including an unlisted winning-side mini-score.
- `odds.books` keeps named books with both selections: `opening`, `last`, raw quote times, resolved UTC times and `lastPreMatchBasis`. Missing or suspended prices stay null. `odds.summary` gives the best and average last prices independently for each side.
- `espnMatchStatus` is `matched`, `ambiguous` or `not_found`. The `espn` block includes event/competition IDs, athlete IDs in TennisExplorer side order, court, venue, `timeValid`, the ESPN time, matching evidence and score/status/time conflicts. Ambiguous matches have no enrichment. ESPN coverage is limited to overlapping ATP/WTA events.
- `sourceUrls`, `collectedAt`, `detailStatus`, `espnChecked`, `resultObservationHash` and `change` describe provenance, completeness and feed revisions.

`OUTPUT` summarizes delivered rows by tour/day/status, odds coverage and books,
ESPN matching, requests, response bytes, elapsed time, failures, caps and feed
state. `summaryLine` also becomes the run's final status message. Failed dates
are named; a complete source failure fails the run. Partial exports retain
usable records and explain what is missing.

### Output example

**Selected fields only.** This is a captured Noskova–Gauff record from November
10, 2026, with one of its 15 books shown. Omitted fields and books remain in the
full dataset row.

```json
{
  "matchKey": "tennisexplorer:3370033",
  "tour": "WTA",
  "date": "2026-11-10",
  "scheduledStart": "2026-11-10T22:10:00Z",
  "status": "final",
  "sides": [
    {
      "name": "Noskova Linda",
      "players": [
        {
          "nativeId": "noskova",
          "name": "Noskova Linda"
        }
      ]
    },
    {
      "name": "Gauff Coco",
      "players": [
        {
          "nativeId": "gauff",
          "name": "Gauff Coco"
        }
      ]
    }
  ],
  "sets": [
    {
      "set": 1,
      "games": [
        6,
        3
      ],
      "tiebreakPoints": [
        null,
        null
      ]
    },
    {
      "set": 2,
      "games": [
        6,
        3
      ],
      "tiebreakPoints": [
        null,
        null
      ]
    }
  ],
  "odds": {
    "books": [
      {
        "name": "10Bet",
        "selections": [
          {
            "side": 0,
            "opening": 2.35,
            "last": 2.5,
            "lastUpdatedAt": "2026-11-10T21:53:00Z"
          },
          {
            "side": 1,
            "opening": 1.55,
            "last": 1.5,
            "lastUpdatedAt": "2026-11-10T21:53:00Z"
          }
        ]
      }
    ]
  },
  "espnMatchStatus": "matched",
  "espn": {
    "eventId": "382-2026",
    "competitionId": "187375",
    "athleteIds": [
      [
        "6970"
      ],
      [
        "3626"
      ]
    ],
    "court": "Indian Wells Tennis Garden",
    "timeValid": true
  },
  "collectedAt": "2026-11-11T21:28:09.677239Z"
}
```

### Pricing

**$0.004 per match record ($4.00 per 1,000) plus $0.005 per run start; odds from every listed bookmaker and ESPN enrichment are included at no extra charge**. Under pay per event there is no separate compute or proxy charge. The default memory is 512 MB.

| Delivered matches | Total for one run |
| ---: | ---: |
| 0 | $0.005 |
| 20 | $0.085 |
| 100 | $0.405 |
| 1,000 | $4.005 |

Charge limits restrict rows delivered. `OUTPUT` says “allowed N of M” when a
limit truncates the requested delivery. The 1,000-match cost is arithmetic for
one run; acquisition limits may require several runs and therefore several
start fees.

### Limits and measured coverage

On November 11, 2026, the ATP/WTA singles prefill delivered 17 of yesterday's
completed matches. All 17 had two-sided last prices from at least three books;
all 17 matched ESPN after name normalization. Two fixture records, two
Challenger records and one ITF men's record also had multiple books. A WTA
doubles record had 13 named books and a matching ESPN competition. These small
samples do not establish universal lower-tier or doubles coverage.

Two sampled matches from each of November 10 in 2010, 2020 and 2023 retained
multi-book odds. The 2010 sample was ATP only; there were no WTA main-tour
matches on that chosen day. This demonstrates some 16-year-old odds, not a
complete archive or a guaranteed earliest year. Check every backfill's coverage.

The current singles sample showed 10Bet, 1xBet, bet-at-home, bet365, Betfair,
Betsson, BetVictor, Betway, bwin, Coral, Interwetten, Ladbrokes, Pinnacle, Unibet
and William Hill. Betsafe and BoyleSports also appeared in older samples.
Book names are the source's labels; no regional edition or executable price
is guaranteed.

“Last” means the source's last available quoted price, using a resolvable
pre-start history entry where available. It is an estimate for closing-odds
research, not a certified official close. Raw timestamps are retained; uncertain
times remain null with an unknown basis. Opening labels are preserved even if
an opening looks unusual. Prices include bookmaker margin, and retirement or
walkover settlement rules can differ between books.

Each run is limited to 14 days, 1,000 rows and 160 request attempts, including
retries and enrichment. Collection stops at a 64 MB response budget (up to three
already active responses can finish), or after 780 seconds, leaving time within
the recommended 900-second platform timeout to save the summary. Details use
at most three concurrent requests per host, with at least 0.5 seconds between starts and bounded
retry backoff. Rows are saved during collection. Large exports finish partially;
inspect `OUTPUT.continueFromDate` and the “Continue from date” status message.
Continue inclusively with the same results-feed state key to skip delivered rows.
A 1,000-match rich export requires multiple runs because each match needs a
detail request. No one-run 1,000-match backfill or fixed completion speed is promised.
A 120-match offline replay with the native parser took **132.0 seconds
(54.6 matches/minute)** and peaked at **182.8 MiB RSS**, measured locally under
one-eighth-core emulation on Python 3.14.8. This includes local SDK dataset
writes and a saved-feed ledger, with full captured pages and stubbed HTTP.
These are local measurements pending coordinator confirmation on the platform;
source latency, retries and remote storage affect actual speed. See the
[performance report](../../docs/quality/2026-11-11-tennis-perf/REPORT.md).
Country, category, outdoor/indoor detail, prize money, duration and rankings can
be absent. Team events, juniors, UTR and exhibitions are excluded. No live
scores, point-by-point data, serve statistics or player prize payouts are supplied.

### FAQ

**Can I export CSV or Excel?** Yes, through Apify's dataset exports. JSON retains
nested pairs, sets and book selections most directly.

**Does a missing book mean no odds existed?** No. It means no supported quote was
listed in that captured match page, or the summary identifies a detail failure.

**Does ESPN replace the TennisExplorer result?** No. Both observations are kept,
with conflicts visible. Uncertain identity matches remain unenriched.

**Can a feed miss a late result?** Yes, if it falls outside your next date window.
Use overlapping completed days and inspect partial failures. Feed history is
scoped to your selected tours, draw types, filters and odds/fixture options.

**Is this an official feed?** No. It is an independent collector of the listed
sources. Coverage, corrections and continued availability depend on them.

# Actor input Schema

## `tours` (type: `array`):

Omitted: ATP and WTA. Empty is an error. Lower tiers include only what TennisExplorer lists.

## `matchTypes` (type: `array`):

Omitted: singles. Doubles retain both members of each pair.

## `dateFrom` (type: `string`):

Inclusive Prague calendar date, YYYY-MM-DD. Supply both dates; maximum 14 days. Dates since 2000 supported as requests, with source-dependent coverage.

## `dateTo` (type: `string`):

Inclusive Prague calendar date, YYYY-MM-DD. Supply both dates; maximum 14 days. Dates since 2000 supported as requests, with source-dependent coverage.

## `lastDays` (type: `integer`):

Alternative to dates: last 1–14 completed Prague days, ending yesterday. Omitted dates and lastDays: yesterday.

## `players` (type: `array`):

Optional Latin name tokens or native player IDs. Match listed names (surname recommended); omit for all. Empty is an error. Up to 50 unique values of 1–200 characters; duplicates ignoring case and outer whitespace are rejected.

## `tournaments` (type: `array`):

Optional listed tournament name substrings or native edition IDs. Omit for all; explicit empty is an error. Up to 50 unique values of 1–200 characters; duplicates ignoring case and outer whitespace are rejected.

## `includeOdds` (type: `boolean`):

Opening and last listed match-winner decimal prices from named books; availability varies.

## `includeFixtures` (type: `boolean`):

Allow today/future dates, up to 7 days ahead. Collects scheduled matches and their listed pre-match odds; no live scores. Cannot combine with onlyNewSinceLastRun.

## `enrichWithEspn` (type: `boolean`):

Match by names, date, tour and draw. Ambiguous and absent matches stay explicit.

## `onlyNewSinceLastRun` (type: `boolean`):

First run is a labelled baseline. Later runs deliver only unseen match keys or changed result states/scores. Use the same state key and filters; serialise runs. Results only: includeFixtures must be false. Overlapping platform jobs require external serialization.

## `stateKey` (type: `string`):

Record key in the named tennis-results-odds-state store. Omitted: derived from filters. 1–64 letters, digits, ! \_ . apostrophe ( ) -; requires feed mode.

## `maxResults` (type: `integer`):

Omitted: 20. Range 1–1,000. Stops at 160 attempts, a 64 MB response budget or 780 seconds; OUTPUT gives a continuation date. Large rich backfills require multiple runs.

## `proxyConfiguration` (type: `object`):

Omitted: direct connections. Local runs never initialise Apify Proxy.

## Actor input object example

```json
{
  "tours": [
    "ATP",
    "WTA"
  ],
  "matchTypes": [
    "singles"
  ],
  "lastDays": 1,
  "includeOdds": true,
  "includeFixtures": false,
  "enrichWithEspn": true,
  "onlyNewSinceLastRun": false,
  "maxResults": 20
}
```

# Actor output Schema

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

No description

## `summary` (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 = {
    "tours": [
        "ATP",
        "WTA"
    ],
    "matchTypes": [
        "singles"
    ],
    "lastDays": 1,
    "includeOdds": true,
    "includeFixtures": false,
    "enrichWithEspn": true,
    "onlyNewSinceLastRun": false,
    "maxResults": 20
};

// Run the Actor and wait for it to finish
const run = await client.actor("automatic/tennis-results-odds").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 = {
    "tours": [
        "ATP",
        "WTA",
    ],
    "matchTypes": ["singles"],
    "lastDays": 1,
    "includeOdds": True,
    "includeFixtures": False,
    "enrichWithEspn": True,
    "onlyNewSinceLastRun": False,
    "maxResults": 20,
}

# Run the Actor and wait for it to finish
run = client.actor("automatic/tennis-results-odds").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 '{
  "tours": [
    "ATP",
    "WTA"
  ],
  "matchTypes": [
    "singles"
  ],
  "lastDays": 1,
  "includeOdds": true,
  "includeFixtures": false,
  "enrichWithEspn": true,
  "onlyNewSinceLastRun": false,
  "maxResults": 20
}' |
apify call automatic/tennis-results-odds --silent --output-dataset

```

## MCP server setup

```json
{
    "mcpServers": {
        "apify": {
            "type": "http",
            "url": "https://mcp.apify.com/?tools=fetch-actor-details,automatic/tennis-results-odds"
        }
    }
}
```

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/XSaY2n11WBpYdNRA7/builds/fr77DT9eola2XOza2/openapi.json
