# Flashscore Win Rate Tracker (`statanow/flashscore-win-rate-tracker`) Actor

Use this FlashScore Win Rate Tracker to collect recent historical matches for a team or player and analyze them with AI, including win/draw/loss trends, goals, home/away splits, incidents, and sport-specific insights. Export results, run via API, schedule runs, or connect tools.

- **URL**: https://apify.com/statanow/flashscore-win-rate-tracker.md
- **Developed by:** [statanow](https://apify.com/statanow) (community)
- **Categories:** E-commerce
- **Stats:** 3 total users, 3 monthly users, 100.0% runs succeeded, 3 bookmarks
- **User rating**: No ratings yet

## Pricing

from $0.25 / result

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/platform/actors/running/actors-in-store#pay-per-event

## What's an Apify Actor?

Actors are a software tools running on the Apify platform, for all kinds of web data extraction and automation use cases.
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.

In JavaScript/TypeScript projects, use official [JavaScript/TypeScript client](https://docs.apify.com/api/client/js.md):

```bash
npm install apify-client
```

In Python projects, use official [Python client library](https://docs.apify.com/api/client/python.md):

```bash
pip install apify-client
```

In shell scripts, use [Apify CLI](https://docs.apify.com/cli/docs.md):

````bash
# MacOS / Linux
curl -fsSL https://apify.com/install-cli.sh | bash
# Windows
irm https://apify.com/install-cli.ps1 | iex
```bash

In AI frameworks, you might use the [Apify MCP server](https://docs.apify.com/platform/integrations/mcp.md).

If your project is in a different language, use 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

### ⚽ What can FlashScore Win Rate Tracker do?

FlashScore Win Rate Tracker **collects recent historical matches for a team or player from FlashScore via a downstream Apify Actor**, then **analyzes the raw sports JSON with Gemini** and returns a structured report in one final output.

Just run the Actor, and you will immediately get:

- 🔎 Search for a team or player by name  
- 🏆 Recent completed matches for the selected sport  
- 📊 Trends and win / draw / loss percentages  
- 🥅 Goals scored and conceded, goal difference, and averages  
- 🏠 Home and away match breakdowns  
- 🟨 Incident analysis (goals, cards, substitutions, penalties, and other sport-specific events when available)  
- 🧠 AI-generated structured analysis in your chosen language  
- 📦 Raw scraper data stored together with the final analytical result  
- ⌚️ Scheduled runs, exports, and integrations through **API endpoints and webhooks**

Use this Actor to track form, compare recent results, monitor consistency, build dashboards, support internal scouting workflows, or create compact sports summaries based on FlashScore data.

### 📊 What FlashScore data can be analyzed?

Each run can include structured match data and analytics, including:

| | |
|---|---|
| 🏷️ Sport type | 🔎 Team or player name |
| 🆔 Match IDs | 🏆 Tournament / league |
| 📅 Match kickoff time | ⚔️ Home and away team |
| 🥅 Score | 📈 Win / draw / loss percentages |
| ⚽ Goals scored / conceded | 🏠 Home and away breakdowns |
| 📜 Event / incident history | 🏅 Top players or category leaders |
| 🧪 Validation checks | 📝 Human-readable summaries |

The final result includes a `generatedAt` timestamp, normalized `input`, a `matches` section with indexed match metadata, scraper metadata, structured `analysis`, and the full `rawScraperOutput` used to build the report.

### How to use FlashScore Win Rate Tracker

1. [Create](https://console.apify.com/) a free Apify account.
2. Open your Actor in Apify Console.
3. Fill in the input fields:
   - `sport`
   - `name`
   - `historicalMatches`
   - `outputLanguage`
   - `additionalPrompt`
4. Click **Start** and wait for the run to finish.
5. Download the final result from **Output**, review the default **Dataset**, or use it via API.

### 🧠 How it works

1. The Actor validates and normalizes your input.
2. It calls the downstream Actor `statanow/flashscore-scraper-team-statistic` with the parameters `sport`, `entity_name`, and `historical_matches`.
3. The raw scraper result is stored in the default key-value store under the key **`SCRAPER_OUTPUT`**.
4. The scraper JSON is compacted and checked against an internal size limit.
5. Gemini analyzes the raw data and returns **schema-constrained JSON** containing both machine-friendly metrics and short human-readable summaries.
6. The Actor stores the final report under the key **`OUTPUT`** and also adds it to the default dataset.

### 🏅 Sports with tailored analysis

This Actor includes analysis instructions tailored to specific sports for many common FlashScore categories. If a selected sport does not have its own dedicated configuration, a universal structured analysis is used.

| | | | | |
|---|---|---|---|---|
| ⚽ Football | 🏀 Basketball | 🎾 Tennis | 🏒 Hockey | ⚾ Baseball |
| 🏐 Volleyball | 🤾 Handball | 🏓 Table tennis | 🏉 Rugby union / rugby league | 🏸 Badminton |
| 🥅 Futsal | 🏈 American football | 🥊 Boxing / MMA | ⛳ Golf | 🌊 Water polo |

### ⬇️ Input

FlashScore Win Rate Tracker works immediately after launch, but **requires input that defines the sport and the team or player to analyze**.

### ✅ Supported sport input values

The `sport` field uses the same predefined select list as the downstream FlashScore Team Statistic scraper. Supported values:

`skiing`, `american_football`, `badminton`, `bandy`, `baseball`, `basketball`, `beach_soccer`, `beach_volleyball`, `biathlon`, `boxing`, `cross_country_skiing`, `cycling`, `esports`, `field_hockey`, `floorball`, `football`, `futsal`, `golf`, `handball`, `hockey`, `mma`, `motorsport`, `netball`, `rugby_league`, `rugby_union`, `ski_jumping`, `table_tennis`, `tennis`, `volleyball`, `water_polo`

#### The Actor input can be:

```json
{
  "sport": "football",
  "name": "Barcelona",
  "historicalMatches": 20,
  "outputLanguage": "en",
  "additionalPrompt": ""
}
````

#### Input fields

- `sport` — sport selected from the supported list in the Actor input. Default: `football`
- `name` — required team or player name, for example `Barcelona`
- `historicalMatches` — how many recent completed matches to collect. Default: `20`
- `outputLanguage` — language code or language name for the final report. Default: `en`
- `additionalPrompt` — optional extra instruction for a more specific final response

### ⬆️ Output

After the run is complete, FlashScore Win Rate Tracker stores:

- **`OUTPUT`** in the default key-value store — the final structured analytical result
- **`SCRAPER_OUTPUT`** in the default key-value store — the raw payload from the downstream scraper
- **1 dataset item** in the default dataset — the same final report for API / export scenarios

#### Example of the final output structure

```json
{
  "status": "success",
  "generatedAt": "2026-03-27T18:02:00+00:00",
  "input": {
    "sport": "football",
    "name": "Barcelona",
    "historicalMatches": 20,
    "outputLanguage": "en",
    "additionalPrompt": "",
    "tokenBudgetPolicy": {
      "maxOutputTokens": 3400,
      "additionalPromptMultiplier": 1.0
    },
    "jsonBudgetPolicy": {
      "maxJsonChars": 396000,
      "calculatedInternally": true,
      "calculatedFromHistoricalMatches": true,
      "sportAware": true
    }
  },
  "matches": {
    "count": 20,
    "matchIds": ["123456", "123457"],
    "index": [
      {
        "match_id": "123456",
        "kickoff": "2026-03-20T20:00:00Z",
        "competition": "SPAIN: LaLiga",
        "home_team": "Barcelona",
        "away_team": "Valencia",
        "score": "3-1",
        "url": "https://www.flashscore.com/match/..."
      }
    ]
  },
  "scraper": {
    "actorId": "statanow/flashscore-scraper-team-statistic",
    "runId": "abc123",
    "outputSource": "key_value_store",
    "outputKey": "OUTPUT",
    "defaultDatasetId": "...",
    "defaultKeyValueStoreId": "...",
    "rawOutputStoredAs": "SCRAPER_OUTPUT"
  },
  "analysis": {
    "provider": "gemini",
    "status": "completed",
    "model": "gemini-2.5-flash",
    "inputJsonChars": 185420,
    "maxJsonChars": 396000,
    "result": {
      "language": "en",
      "data_json": {
        "match_ids": ["123456", "123457"],
        "overall_statistics": [],
        "percentages": [],
        "goals": [],
        "breakdowns": [],
        "home_away": [],
        "incidents": [],
        "tops": [],
        "validations": [],
        "final_summary": "Compact analytical summary"
      },
      "text_json": {
        "general_statistics": "...",
        "percentages": "...",
        "goals": "...",
        "breakdowns": "...",
        "home_away": "...",
        "incidents": "...",
        "tops": "...",
        "validation": "...",
        "final_summary": "..."
      },
      "missing_fields": [],
      "warnings": []
    }
  },
  "rawScraperOutput": {}
}
```

### ❓ FAQ

#### Does it collect live matches?

No. This Actor is built for **historical match analysis**. It requests the latest completed matches for the selected team or player through the downstream FlashScore team-statistics scraper, then analyzes that data.

#### Can the final analysis be customized?

Yes. Use `outputLanguage` to change the language of the response, and `additionalPrompt` to request a more specific summary, analysis angle, or derived insight.

#### Where is the raw scraper result stored?

The raw downstream payload is stored in the default key-value store under the key **`SCRAPER_OUTPUT`** and is also embedded in the final **`OUTPUT`** payload as **`rawScraperOutput`**.

#### Can it be used in automations or external code?

Yes. You can run it from Apify Console, call it through the API, schedule it, or connect it to webhooks and external workflows.

#### Does it work only for football?

No. Football is the default, but the Actor includes sport-aware analysis rules for several sports. If the selected sport does not have a dedicated configuration, it falls back to a universal structured analysis based on the scraper JSON.

# Actor input Schema

## `sport` (type: `string`):

Choose a sport from the supported list.

## `name` (type: `string`):

Example: Barcelona

## `historicalMatches` (type: `integer`):

How many recent completed matches to scrape.

## `outputLanguage` (type: `string`):

Language code or human-readable language name for the final report. Default is English.

## `additionalPrompt` (type: `string`):

Optional extra instruction. Leave empty by default. When empty, Gemini uses the standard token budget without any extra allocation.

## `geminiApiKey` (type: `string`):

Optional. Use only if you want to provide your own Gemini key per run. Prefer GEMINI\_API\_KEY as a secret Actor environment variable for the public Actor.

## Actor input object example

```json
{
  "sport": "football",
  "name": "Arsenal",
  "historicalMatches": 3,
  "outputLanguage": "en",
  "additionalPrompt": ""
}
```

# Actor output Schema

## `datasetItems` (type: `string`):

No description

## `kvStoreKeys` (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 = {
    "sport": "football",
    "name": "Arsenal",
    "historicalMatches": 3,
    "outputLanguage": "en",
    "additionalPrompt": ""
};

// Run the Actor and wait for it to finish
const run = await client.actor("statanow/flashscore-win-rate-tracker").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 = {
    "sport": "football",
    "name": "Arsenal",
    "historicalMatches": 3,
    "outputLanguage": "en",
    "additionalPrompt": "",
}

# Run the Actor and wait for it to finish
run = client.actor("statanow/flashscore-win-rate-tracker").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 '{
  "sport": "football",
  "name": "Arsenal",
  "historicalMatches": 3,
  "outputLanguage": "en",
  "additionalPrompt": ""
}' |
apify call statanow/flashscore-win-rate-tracker --silent --output-dataset

```

## MCP server setup

```json
{
    "mcpServers": {
        "apify": {
            "command": "npx",
            "args": [
                "mcp-remote",
                "https://mcp.apify.com/?tools=statanow/flashscore-win-rate-tracker",
                "--header",
                "Authorization: Bearer <YOUR_API_TOKEN>"
            ]
        }
    }
}

```

## OpenAPI specification

```json
{
    "openapi": "3.0.1",
    "info": {
        "title": "Flashscore Win Rate Tracker",
        "description": "Use this FlashScore Win Rate Tracker to collect recent historical matches for a team or player and analyze them with AI, including win/draw/loss trends, goals, home/away splits, incidents, and sport-specific insights. Export results, run via API, schedule runs, or connect tools.",
        "version": "0.1",
        "x-build-id": "9wQAqCDGuOp87nrbs"
    },
    "servers": [
        {
            "url": "https://api.apify.com/v2"
        }
    ],
    "paths": {
        "/acts/statanow~flashscore-win-rate-tracker/run-sync-get-dataset-items": {
            "post": {
                "operationId": "run-sync-get-dataset-items-statanow-flashscore-win-rate-tracker",
                "x-openai-isConsequential": false,
                "summary": "Executes an Actor, waits for its completion, and returns Actor's dataset items in response.",
                "tags": [
                    "Run Actor"
                ],
                "requestBody": {
                    "required": true,
                    "content": {
                        "application/json": {
                            "schema": {
                                "$ref": "#/components/schemas/inputSchema"
                            }
                        }
                    }
                },
                "parameters": [
                    {
                        "name": "token",
                        "in": "query",
                        "required": true,
                        "schema": {
                            "type": "string"
                        },
                        "description": "Enter your Apify token here"
                    }
                ],
                "responses": {
                    "200": {
                        "description": "OK"
                    }
                }
            }
        },
        "/acts/statanow~flashscore-win-rate-tracker/runs": {
            "post": {
                "operationId": "runs-sync-statanow-flashscore-win-rate-tracker",
                "x-openai-isConsequential": false,
                "summary": "Executes an Actor and returns information about the initiated run in response.",
                "tags": [
                    "Run Actor"
                ],
                "requestBody": {
                    "required": true,
                    "content": {
                        "application/json": {
                            "schema": {
                                "$ref": "#/components/schemas/inputSchema"
                            }
                        }
                    }
                },
                "parameters": [
                    {
                        "name": "token",
                        "in": "query",
                        "required": true,
                        "schema": {
                            "type": "string"
                        },
                        "description": "Enter your Apify token here"
                    }
                ],
                "responses": {
                    "200": {
                        "description": "OK",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "$ref": "#/components/schemas/runsResponseSchema"
                                }
                            }
                        }
                    }
                }
            }
        },
        "/acts/statanow~flashscore-win-rate-tracker/run-sync": {
            "post": {
                "operationId": "run-sync-statanow-flashscore-win-rate-tracker",
                "x-openai-isConsequential": false,
                "summary": "Executes an Actor, waits for completion, and returns the OUTPUT from Key-value store in response.",
                "tags": [
                    "Run Actor"
                ],
                "requestBody": {
                    "required": true,
                    "content": {
                        "application/json": {
                            "schema": {
                                "$ref": "#/components/schemas/inputSchema"
                            }
                        }
                    }
                },
                "parameters": [
                    {
                        "name": "token",
                        "in": "query",
                        "required": true,
                        "schema": {
                            "type": "string"
                        },
                        "description": "Enter your Apify token here"
                    }
                ],
                "responses": {
                    "200": {
                        "description": "OK"
                    }
                }
            }
        }
    },
    "components": {
        "schemas": {
            "inputSchema": {
                "type": "object",
                "required": [
                    "name"
                ],
                "properties": {
                    "sport": {
                        "title": "Sport",
                        "enum": [
                            "skiing",
                            "american_football",
                            "badminton",
                            "bandy",
                            "baseball",
                            "basketball",
                            "beach_soccer",
                            "beach_volleyball",
                            "biathlon",
                            "boxing",
                            "cross_country_skiing",
                            "cycling",
                            "esports",
                            "field_hockey",
                            "floorball",
                            "football",
                            "futsal",
                            "golf",
                            "handball",
                            "hockey",
                            "mma",
                            "motorsport",
                            "netball",
                            "rugby_league",
                            "rugby_union",
                            "ski_jumping",
                            "table_tennis",
                            "tennis",
                            "volleyball",
                            "water_polo"
                        ],
                        "type": "string",
                        "description": "Choose a sport from the supported list.",
                        "default": "football"
                    },
                    "name": {
                        "title": "Team or player name",
                        "type": "string",
                        "description": "Example: Barcelona",
                        "default": "Arsenal"
                    },
                    "historicalMatches": {
                        "title": "Historical matches",
                        "minimum": 1,
                        "type": "integer",
                        "description": "How many recent completed matches to scrape.",
                        "default": 3
                    },
                    "outputLanguage": {
                        "title": "Result language",
                        "type": "string",
                        "description": "Language code or human-readable language name for the final report. Default is English.",
                        "default": "en"
                    },
                    "additionalPrompt": {
                        "title": "Additional prompt",
                        "type": "string",
                        "description": "Optional extra instruction. Leave empty by default. When empty, Gemini uses the standard token budget without any extra allocation.",
                        "default": ""
                    },
                    "geminiApiKey": {
                        "title": "Gemini API key",
                        "type": "string",
                        "description": "Optional. Use only if you want to provide your own Gemini key per run. Prefer GEMINI_API_KEY as a secret Actor environment variable for the public Actor."
                    }
                }
            },
            "runsResponseSchema": {
                "type": "object",
                "properties": {
                    "data": {
                        "type": "object",
                        "properties": {
                            "id": {
                                "type": "string"
                            },
                            "actId": {
                                "type": "string"
                            },
                            "userId": {
                                "type": "string"
                            },
                            "startedAt": {
                                "type": "string",
                                "format": "date-time",
                                "example": "2025-01-08T00:00:00.000Z"
                            },
                            "finishedAt": {
                                "type": "string",
                                "format": "date-time",
                                "example": "2025-01-08T00:00:00.000Z"
                            },
                            "status": {
                                "type": "string",
                                "example": "READY"
                            },
                            "meta": {
                                "type": "object",
                                "properties": {
                                    "origin": {
                                        "type": "string",
                                        "example": "API"
                                    },
                                    "userAgent": {
                                        "type": "string"
                                    }
                                }
                            },
                            "stats": {
                                "type": "object",
                                "properties": {
                                    "inputBodyLen": {
                                        "type": "integer",
                                        "example": 2000
                                    },
                                    "rebootCount": {
                                        "type": "integer",
                                        "example": 0
                                    },
                                    "restartCount": {
                                        "type": "integer",
                                        "example": 0
                                    },
                                    "resurrectCount": {
                                        "type": "integer",
                                        "example": 0
                                    },
                                    "computeUnits": {
                                        "type": "integer",
                                        "example": 0
                                    }
                                }
                            },
                            "options": {
                                "type": "object",
                                "properties": {
                                    "build": {
                                        "type": "string",
                                        "example": "latest"
                                    },
                                    "timeoutSecs": {
                                        "type": "integer",
                                        "example": 300
                                    },
                                    "memoryMbytes": {
                                        "type": "integer",
                                        "example": 1024
                                    },
                                    "diskMbytes": {
                                        "type": "integer",
                                        "example": 2048
                                    }
                                }
                            },
                            "buildId": {
                                "type": "string"
                            },
                            "defaultKeyValueStoreId": {
                                "type": "string"
                            },
                            "defaultDatasetId": {
                                "type": "string"
                            },
                            "defaultRequestQueueId": {
                                "type": "string"
                            },
                            "buildNumber": {
                                "type": "string",
                                "example": "1.0.0"
                            },
                            "containerUrl": {
                                "type": "string"
                            },
                            "usage": {
                                "type": "object",
                                "properties": {
                                    "ACTOR_COMPUTE_UNITS": {
                                        "type": "integer",
                                        "example": 0
                                    },
                                    "DATASET_READS": {
                                        "type": "integer",
                                        "example": 0
                                    },
                                    "DATASET_WRITES": {
                                        "type": "integer",
                                        "example": 0
                                    },
                                    "KEY_VALUE_STORE_READS": {
                                        "type": "integer",
                                        "example": 0
                                    },
                                    "KEY_VALUE_STORE_WRITES": {
                                        "type": "integer",
                                        "example": 1
                                    },
                                    "KEY_VALUE_STORE_LISTS": {
                                        "type": "integer",
                                        "example": 0
                                    },
                                    "REQUEST_QUEUE_READS": {
                                        "type": "integer",
                                        "example": 0
                                    },
                                    "REQUEST_QUEUE_WRITES": {
                                        "type": "integer",
                                        "example": 0
                                    },
                                    "DATA_TRANSFER_INTERNAL_GBYTES": {
                                        "type": "integer",
                                        "example": 0
                                    },
                                    "DATA_TRANSFER_EXTERNAL_GBYTES": {
                                        "type": "integer",
                                        "example": 0
                                    },
                                    "PROXY_RESIDENTIAL_TRANSFER_GBYTES": {
                                        "type": "integer",
                                        "example": 0
                                    },
                                    "PROXY_SERPS": {
                                        "type": "integer",
                                        "example": 0
                                    }
                                }
                            },
                            "usageTotalUsd": {
                                "type": "number",
                                "example": 0.00005
                            },
                            "usageUsd": {
                                "type": "object",
                                "properties": {
                                    "ACTOR_COMPUTE_UNITS": {
                                        "type": "integer",
                                        "example": 0
                                    },
                                    "DATASET_READS": {
                                        "type": "integer",
                                        "example": 0
                                    },
                                    "DATASET_WRITES": {
                                        "type": "integer",
                                        "example": 0
                                    },
                                    "KEY_VALUE_STORE_READS": {
                                        "type": "integer",
                                        "example": 0
                                    },
                                    "KEY_VALUE_STORE_WRITES": {
                                        "type": "number",
                                        "example": 0.00005
                                    },
                                    "KEY_VALUE_STORE_LISTS": {
                                        "type": "integer",
                                        "example": 0
                                    },
                                    "REQUEST_QUEUE_READS": {
                                        "type": "integer",
                                        "example": 0
                                    },
                                    "REQUEST_QUEUE_WRITES": {
                                        "type": "integer",
                                        "example": 0
                                    },
                                    "DATA_TRANSFER_INTERNAL_GBYTES": {
                                        "type": "integer",
                                        "example": 0
                                    },
                                    "DATA_TRANSFER_EXTERNAL_GBYTES": {
                                        "type": "integer",
                                        "example": 0
                                    },
                                    "PROXY_RESIDENTIAL_TRANSFER_GBYTES": {
                                        "type": "integer",
                                        "example": 0
                                    },
                                    "PROXY_SERPS": {
                                        "type": "integer",
                                        "example": 0
                                    }
                                }
                            }
                        }
                    }
                }
            }
        }
    }
}
```