# Transfermarkt Global Football Player Scraper (`jungle_synthesizer/transfermarkt-global-football-player-scraper`) Actor

Scrape global football player profiles from Transfermarkt — career, market value history, transfers, agency, caps, injuries. Discover by player ID, club, competition (Premier League, La Liga, MLS, etc.) or search query.

- **URL**: https://apify.com/jungle\_synthesizer/transfermarkt-global-football-player-scraper.md
- **Developed by:** [BowTiedRaccoon](https://apify.com/jungle_synthesizer) (community)
- **Categories:** Sports, Lead generation, Other
- **Stats:** 2 total users, 1 monthly users, 100.0% runs succeeded, NaN bookmarks
- **User rating**: No ratings yet

## Pricing

Pay per event

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

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

## What's an Apify Actor?

Actors are 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

## Transfermarkt Football Player Scraper

Scrape global football player data from [Transfermarkt](https://www.transfermarkt.com) — full identities, market value history, transfers, agency, national team caps, injuries, and suspensions for 1M+ profiles. Powered by the public Transfermarkt JSON API for clean, structured records and the website itself for discovery.

---

### Transfermarkt Football Player Scraper Features

- Returns 40+ fields per player profile, all flattened into Apify-friendly JSON.
- Discovers players four different ways — direct player IDs, club rosters, competition codes, or free-text search. Pick one.
- Pulls full market value history. That's every quarterly valuation Transfermarkt has ever published for a player, including the all-time peak.
- Captures career arcs from youth clubs through senior transfers, with fees and dates where Transfermarkt has them.
- Splits absences into injuries and suspensions. Yellow cards, red cards, sports-court verdicts — they all land in the right bucket.
- Uses the public Transfermarkt JSON API for enrichment, so the per-player payload is rich and consistent rather than scraped from inconsistent HTML.
- Default datacenter proxies handle the CloudFront WAF on listing pages. Switch to residential if you see HTTP 403s.

---

### Who Uses Transfermarkt Player Data?

- **Sports betting and trading firms** — Build market value baselines, surface mispricings around transfers and injuries.
- **Fantasy football platforms** — Power player cards with current clubs, market values, and form context.
- **Football agents and scouts** — Track career arcs, contract expiries, and agency relationships at scale.
- **Sports journalists and analysts** — Pull standardised career histories without copy-pasting from individual profile pages.
- **Academic researchers** — Long-tail labour-economics studies of football transfers, salary trajectories, and migration patterns.
- **Club analytics departments** — Benchmark squad valuations, monitor competing rosters, scout free agents.

---

### How Transfermarkt Football Player Scraper Works

1. **Pick a discovery source.** Pass player IDs directly, hand it club IDs (e.g. 31 for Liverpool, 69261 for Inter Miami), feed it competition codes (GB1 for Premier League, ES1 for La Liga, MLS1 for MLS), or just type a search query. The scraper picks the highest-priority source you've provided.
2. **Discovery resolves to player IDs.** Club rosters and competition pages get parsed for `/spieler/<id>` links. Search queries hit the Transfermarkt schnellsuche endpoint. Direct IDs skip this stage entirely.
3. **Each player gets enriched in parallel** — five Transfermarkt API endpoints fan out per player to pull identity, market value history, transfers, national team caps, and absences.
4. **Records flatten into the dataset.** All array fields are primitive strings (Apify schema requirement), club IDs resolve to names via a cached lookup, nationality IDs resolve to country names.

---

### Input

```json
{
    "playerIds": ["28003", "8198"],
    "maxItems": 10,
    "proxyConfiguration": {
        "useApifyProxy": true
    }
}
````

| Field | Type | Default | Description |
|-------|------|---------|-------------|
| `searchQuery` | string | `""` | Free-text search on transfermarkt.com (e.g. `"messi"`, `"haaland"`, `"bellingham"`). Returns top matches up to `maxItems`. |
| `playerIds` | array | `["28003", "8198"]` | Transfermarkt player IDs (the numeric tail of `/spieler/<id>` URLs). Highest priority — when set, HTML discovery is skipped. |
| `clubIds` | array | `[]` | Transfermarkt club IDs (e.g. `"69261"` for Inter Miami, `"31"` for Liverpool). Pulls every player from each club's current roster. |
| `competitionCodes` | array | `[]` | Transfermarkt competition codes — `GB1` (Premier League), `ES1` (La Liga), `IT1` (Serie A), `L1` (Bundesliga), `FR1` (Ligue 1), `MLS1` (MLS), and so on. Pulls every club, then every player. |
| `maxItems` | integer | `10` | Maximum number of player profiles to scrape. Keep low for test runs. |
| `proxyConfiguration` | object | datacenter | Apify datacenter proxies are the default. Switch to `RESIDENTIAL` only if you see HTTP 403 errors on the HTML pages. |

#### Discovery priority

If you set multiple sources, the scraper picks one in this order:

1. `playerIds`
2. `clubIds`
3. `competitionCodes`
4. `searchQuery`

So if you pass both `playerIds` and `clubIds`, the IDs win.

#### Discovery examples

Scrape an entire Premier League team:

```json
{
    "clubIds": ["31"],
    "maxItems": 30
}
```

Scrape the top of the Bundesliga and get the first 100 players the page yields:

```json
{
    "competitionCodes": ["L1"],
    "maxItems": 100
}
```

Scrape direct player IDs (fastest, no HTML traffic):

```json
{
    "playerIds": ["28003", "8198", "418560", "342229"],
    "maxItems": 4
}
```

***

### Transfermarkt Football Player Scraper Output Fields

```json
{
    "player_id": "28003",
    "profile_url": "https://www.transfermarkt.com/lionel-messi/profil/spieler/28003",
    "full_name": "Lionel Andrés Messi Cuccitini",
    "display_name": "Lionel Messi",
    "date_of_birth": "1987-06-24",
    "age": 38,
    "place_of_birth": "Rosario",
    "country_of_birth": "Argentina",
    "nationality": ["Argentina", "Spain"],
    "gender": "male",
    "position": "Right Winger",
    "position_category": "Striker",
    "foot": "left",
    "height_cm": 170,
    "current_club": "Inter Miami CF",
    "current_club_id": "69261",
    "current_competition": "Major League Soccer",
    "current_competition_code": "MLS1",
    "shirt_number": 10,
    "is_captain": true,
    "contract_until": "2028-12-31",
    "last_contract_renewal": "2025-10-23",
    "market_value_eur": 15000000,
    "market_value_currency": "EUR",
    "market_value_determined": "2025-12-11",
    "previous_market_value_eur": 18000000,
    "highest_market_value_eur": 180000000,
    "highest_market_value_determined": "2018-05-30",
    "market_value_history": [
        "2017 | FC Barcelona | EUR 180.00M",
        "2023 | Inter Miami CF | EUR 30.00M",
        "2024 | Inter Miami CF | EUR 15.00M"
    ],
    "agent": "Relatives",
    "agency": "",
    "agency_id": "1207",
    "youth_clubs": ["Grandoli FC (1992-1995)", "Newell's Old Boys (1995-2000)"],
    "career_history": [
        "FC Barcelona -> Paris Saint-Germain | 2021-08-10 | Free Transfer | 21/22",
        "Paris Saint-Germain -> Inter Miami CF | 2023-07-15 | Free Transfer | 23/24"
    ],
    "total_transfer_fees_eur": 0,
    "international_team": "Argentina",
    "international_caps": 198,
    "international_goals": 116,
    "national_team_history": [
        "Argentina | 198 apps | 116 goals | CURRENT_NATIONAL_PLAYER",
        "Argentina U20 | 18 apps | 14 goals | FORMER_NATIONAL_PLAYER"
    ],
    "injuries": [],
    "suspensions": [
        "2025-07-25 to 2025-07-28 | Suspension through sports court | 1 game"
    ],
    "photo_url": "https://img.a.transfermarkt.technology/portrait/big/28003-1771694720.jpg",
    "scraped_at": "2026-05-02T15:53:00.000Z"
}
```

| Field | Type | Description |
|-------|------|-------------|
| `player_id` | string | Transfermarkt numeric player ID. |
| `profile_url` | string | Canonical player profile URL on transfermarkt.com. |
| `full_name` | string | Full legal name (passport name from Transfermarkt). |
| `display_name` | string | Common display name. |
| `short_name` | string | Initial-and-surname short form. |
| `nickname` | string | Artist or nickname. Often empty for non-Brazilian players. |
| `date_of_birth` | string | YYYY-MM-DD. |
| `age` | number | Current age in years. |
| `place_of_birth` | string | Birthplace city. |
| `country_of_birth` | string | Birthplace country name. |
| `nationality` | array of strings | Nationality country names. Most players have one; dual nationals get both. |
| `gender` | string | `male` or `female`. |
| `position` | string | Primary position (e.g. Right Winger, Centre-Forward, Goalkeeper). |
| `position_category` | string | Broad group — Goalkeeper, Defender, Midfielder, Striker. |
| `foot` | string | Preferred foot — `left`, `right`, or `both`. |
| `height_cm` | number | Height in centimetres. |
| `current_club` | string | Current club name. Empty if retired or without contract. |
| `current_club_id` | string | Current club's Transfermarkt ID. |
| `current_competition` | string | Current league or competition name. |
| `current_competition_code` | string | Current competition's Transfermarkt code (`GB1`, `ES1`, `MLS1`, etc.). |
| `shirt_number` | number | Current shirt number at club. |
| `is_captain` | boolean | Whether the player is the current club captain. |
| `contract_until` | string | Current contract expiry date (YYYY-MM-DD). |
| `last_contract_renewal` | string | Date of last contract renewal. |
| `market_value_eur` | number | Current market value in EUR. |
| `market_value_currency` | string | Always `EUR`. |
| `market_value_determined` | string | Date the current market value was last set. |
| `previous_market_value_eur` | number | Previous published market value before the most recent update. |
| `highest_market_value_eur` | number | All-time peak market value in EUR. |
| `highest_market_value_determined` | string | Date the all-time peak was set. |
| `market_value_history` | array of strings | `"YYYY | club_name | EUR X.XXm"` entries, oldest first. |
| `agent` | string | Player's individual agent or consultant. |
| `agency` | string | Player's agency name (e.g. `CAA Stellar`, `Wasserman`). |
| `agency_id` | string | Transfermarkt agency ID. |
| `youth_clubs` | array of strings | `"Club Name (start-end)"` entries. |
| `career_history` | array of strings | Senior club moves: `"from -> to | YYYY-MM-DD | fee | season"`. |
| `total_transfer_fees_eur` | number | Sum of disclosed transfer fees across senior career. |
| `international_team` | string | Current senior national team name (or empty if uncapped). |
| `international_caps` | number | Total senior international appearances. |
| `international_goals` | number | Total senior international goals. |
| `national_team_history` | array of strings | All national-team levels with apps, goals, and current/former status. |
| `injuries` | array of strings | `"YYYY-MM-DD to YYYY-MM-DD | name | N games"` entries. |
| `suspensions` | array of strings | Same format. Includes red/yellow card suspensions, sports-court rulings, and call-ups. |
| `photo_url` | string | Player portrait URL. |
| `scraped_at` | string | ISO timestamp the record was scraped. |

***

### FAQ

#### How do I scrape Transfermarkt player data?

Transfermarkt Football Player Scraper accepts four discovery modes — direct player IDs, club IDs, competition codes, or a free-text search query. Pass any one of them in the input, set `maxItems`, and the scraper handles the rest. Player IDs are the numeric tail of any `/spieler/<id>` URL; club IDs come from `/verein/<id>` URLs; competition codes are the short codes Transfermarkt uses internally (`GB1`, `ES1`, `IT1`, `L1`, `FR1`, `MLS1`, etc.).

#### How much does Transfermarkt Football Player Scraper cost to run?

Transfermarkt Football Player Scraper uses Pay-Per-Event pricing — `$0.10` per actor start plus `$0.001` per player record returned. A 100-player run costs 20 cents. A 10,000-player crawl costs about $10.

#### What data can I get from Transfermarkt?

Transfermarkt Football Player Scraper returns 40+ fields per player — full identity (name, date of birth, place of birth, nationalities, gender), physical attributes (height, foot, position), current contract (club, competition, shirt number, captaincy, contract dates), market value (current, previous, all-time peak, plus full history), career arc (youth clubs, senior transfers with fees and dates), national team record (caps, goals per team), and an absence log split into injuries and suspensions.

#### Does Transfermarkt Football Player Scraper need proxies?

Transfermarkt Football Player Scraper defaults to Apify datacenter proxies, which clear Transfermarkt's CloudFront WAF on the listing pages without trouble. The Transfermarkt JSON API itself has no anti-bot layer. If you see HTTP 403 errors during a large search-query or club-roster crawl, switch to residential.

#### Can I scrape an entire league or just specific clubs?

Transfermarkt Football Player Scraper handles both. Pass a competition code (e.g. `GB1` for Premier League) to walk every club in that league and pull their players. Pass specific club IDs to scope to those clubs only. `maxItems` caps the total players returned regardless of how many clubs are in scope.

#### How fresh is Transfermarkt market value data?

Transfermarkt updates market values quarterly (with major refreshes in December and June) and logs transfers in real time during the windows. Each record includes a `market_value_determined` date so you can see exactly when each valuation was set.

***

### Need More Features?

Open an issue at the [OrbTop actor support inbox](mailto:actor-support@orbtop.com) and we'll consider it for the next release.

### Why Use Transfermarkt Football Player Scraper?

- **40+ fields per player** — Identity, contract, market value history, full career arc, national caps, agency, injuries, and suspensions all in one record.
- **Four discovery modes** — Direct IDs, club rosters, league walks, or free-text search. Use whichever fits your workflow.
- **Public JSON API enrichment** — The hard data (career history, market values, transfers) comes from Transfermarkt's own structured API, not flaky HTML parsing.
- **Pay-Per-Event pricing** — `$0.001` per player record. Run 100 or 100,000, you pay only for what you get.

# Actor input Schema

## `sp_intended_usage` (type: `string`):

Please describe how you plan to use the data extracted by this crawler.

## `sp_improvement_suggestions` (type: `string`):

Provide any feedback or suggestions for improvements.

## `sp_contact` (type: `string`):

Provide your email address so we can get in touch with you.

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

Free-text search on transfermarkt.com (e.g. 'messi', 'haaland', 'bellingham'). Returns the top matching players, capped by maxItems.

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

Transfermarkt player IDs (the numeric tail of /spieler/<id> URLs). Skips HTML discovery and goes straight to the API.

## `clubIds` (type: `array`):

Transfermarkt club IDs (numeric tail of /verein/<id> URLs, e.g. 69261 for Inter Miami CF, 31 for Liverpool FC). Pulls every player from each club's current roster.

## `competitionCodes` (type: `array`):

Transfermarkt competition codes (e.g. GB1=Premier League, ES1=La Liga, IT1=Serie A, L1=Bundesliga, FR1=Ligue 1, MLS1=MLS). Pulls every club, then every player.

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

Maximum number of player profiles to scrape. Keep low (5-15) for quick test runs; raise for production crawls.

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

Apify datacenter proxies are the default — they handle Transfermarkt's CloudFront WAF reliably. Switch to RESIDENTIAL only if you see HTTP 403 errors on HTML pages.

## Actor input object example

```json
{
  "sp_intended_usage": "Describe your intended use...",
  "sp_improvement_suggestions": "Share your suggestions here...",
  "sp_contact": "Share your email here...",
  "playerIds": [
    "28003",
    "8198"
  ],
  "clubIds": [],
  "competitionCodes": [],
  "maxItems": 10,
  "proxyConfiguration": {
    "useApifyProxy": true
  }
}
```

# Actor output Schema

## `results` (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 = {
    "sp_intended_usage": "Describe your intended use...",
    "sp_improvement_suggestions": "Share your suggestions here...",
    "sp_contact": "Share your email here...",
    "searchQuery": "",
    "playerIds": [
        "28003",
        "8198"
    ],
    "clubIds": [],
    "competitionCodes": [],
    "maxItems": 10,
    "proxyConfiguration": {
        "useApifyProxy": true
    }
};

// Run the Actor and wait for it to finish
const run = await client.actor("jungle_synthesizer/transfermarkt-global-football-player-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 = {
    "sp_intended_usage": "Describe your intended use...",
    "sp_improvement_suggestions": "Share your suggestions here...",
    "sp_contact": "Share your email here...",
    "searchQuery": "",
    "playerIds": [
        "28003",
        "8198",
    ],
    "clubIds": [],
    "competitionCodes": [],
    "maxItems": 10,
    "proxyConfiguration": { "useApifyProxy": True },
}

# Run the Actor and wait for it to finish
run = client.actor("jungle_synthesizer/transfermarkt-global-football-player-scraper").call(run_input=run_input)

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

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

```

## CLI example

```bash
echo '{
  "sp_intended_usage": "Describe your intended use...",
  "sp_improvement_suggestions": "Share your suggestions here...",
  "sp_contact": "Share your email here...",
  "searchQuery": "",
  "playerIds": [
    "28003",
    "8198"
  ],
  "clubIds": [],
  "competitionCodes": [],
  "maxItems": 10,
  "proxyConfiguration": {
    "useApifyProxy": true
  }
}' |
apify call jungle_synthesizer/transfermarkt-global-football-player-scraper --silent --output-dataset

```

## MCP server setup

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

```

## OpenAPI specification

```json
{
    "openapi": "3.0.1",
    "info": {
        "title": "Transfermarkt Global Football Player Scraper",
        "description": "Scrape global football player profiles from Transfermarkt — career, market value history, transfers, agency, caps, injuries. Discover by player ID, club, competition (Premier League, La Liga, MLS, etc.) or search query.",
        "version": "0.1",
        "x-build-id": "zaWJoZdT2quxJvbh2"
    },
    "servers": [
        {
            "url": "https://api.apify.com/v2"
        }
    ],
    "paths": {
        "/acts/jungle_synthesizer~transfermarkt-global-football-player-scraper/run-sync-get-dataset-items": {
            "post": {
                "operationId": "run-sync-get-dataset-items-jungle_synthesizer-transfermarkt-global-football-player-scraper",
                "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/jungle_synthesizer~transfermarkt-global-football-player-scraper/runs": {
            "post": {
                "operationId": "runs-sync-jungle_synthesizer-transfermarkt-global-football-player-scraper",
                "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/jungle_synthesizer~transfermarkt-global-football-player-scraper/run-sync": {
            "post": {
                "operationId": "run-sync-jungle_synthesizer-transfermarkt-global-football-player-scraper",
                "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",
                "properties": {
                    "sp_intended_usage": {
                        "title": "What is the intended usage of this data?",
                        "minLength": 1,
                        "type": "string",
                        "description": "Please describe how you plan to use the data extracted by this crawler."
                    },
                    "sp_improvement_suggestions": {
                        "title": "How can we improve this crawler for you?",
                        "minLength": 1,
                        "type": "string",
                        "description": "Provide any feedback or suggestions for improvements."
                    },
                    "sp_contact": {
                        "title": "Contact Email",
                        "minLength": 1,
                        "type": "string",
                        "description": "Provide your email address so we can get in touch with you."
                    },
                    "searchQuery": {
                        "title": "Player Search Query",
                        "type": "string",
                        "description": "Free-text search on transfermarkt.com (e.g. 'messi', 'haaland', 'bellingham'). Returns the top matching players, capped by maxItems."
                    },
                    "playerIds": {
                        "title": "Player IDs (direct lookup)",
                        "type": "array",
                        "description": "Transfermarkt player IDs (the numeric tail of /spieler/<id> URLs). Skips HTML discovery and goes straight to the API.",
                        "items": {
                            "type": "string"
                        }
                    },
                    "clubIds": {
                        "title": "Club IDs",
                        "type": "array",
                        "description": "Transfermarkt club IDs (numeric tail of /verein/<id> URLs, e.g. 69261 for Inter Miami CF, 31 for Liverpool FC). Pulls every player from each club's current roster.",
                        "items": {
                            "type": "string"
                        }
                    },
                    "competitionCodes": {
                        "title": "Competition Codes",
                        "type": "array",
                        "description": "Transfermarkt competition codes (e.g. GB1=Premier League, ES1=La Liga, IT1=Serie A, L1=Bundesliga, FR1=Ligue 1, MLS1=MLS). Pulls every club, then every player.",
                        "items": {
                            "type": "string"
                        }
                    },
                    "maxItems": {
                        "title": "Max Players",
                        "minimum": 1,
                        "maximum": 100000,
                        "type": "integer",
                        "description": "Maximum number of player profiles to scrape. Keep low (5-15) for quick test runs; raise for production crawls.",
                        "default": 10
                    },
                    "proxyConfiguration": {
                        "title": "Proxy configuration",
                        "type": "object",
                        "description": "Apify datacenter proxies are the default — they handle Transfermarkt's CloudFront WAF reliably. Switch to RESIDENTIAL only if you see HTTP 403 errors on HTML pages."
                    }
                }
            },
            "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
                                    }
                                }
                            }
                        }
                    }
                }
            }
        }
    }
}
```
