# Transfermarkt Scraper - Player Market Values & Transfers (`bovi/transfermarkt-scraper`) Actor Scrape Transfermarkt (transfermarkt.com) football player data: market values, squads, transfers, and rankings. Returns 25+ fields per player — name, club, position, age, nationality, market value (current + peak), contract, agent, and transfer history. No login or API key. Pay per player record. - **URL**: https://apify.com/bovi/transfermarkt-scraper.md - **Developed by:** [Vitalii Bondarev](https://apify.com/bovi) (community) - **Categories:** Sports - **Stats:** 2 total users, 1 monthly users, 100.0% runs succeeded, NaN bookmarks - **User rating**: No ratings yet ## Pricing from $3.00 / 1,000 player 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/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 Scraper - Player Market Values & Transfers Scrape **football player data** from [Transfermarkt](https://www.transfermarkt.com) — the world's reference for **market values**, squads, and transfers. This **Transfermarkt Scraper** returns **27+ fields per player**: name, current club, league, position, age, nationality, current and peak market value, full market-value history, contract expiry, agent, shirt number, profile image, and full transfer history. Scrape a single player, a whole club squad, or **an entire league in one run**. No login, no API key, no proxy required for standard volumes. Pay per player record at **€3.00 per 1,000 results** — and **no charge for the actor start**, unlike most competitors. ### Why this Transfermarkt Scraper - **Whole-league scraping** — paste a competition code (`GB1`, `ES1`, `IT1`, `L1`, `FR1`, `MLS1`) and get every club's full squad in one call. Most scrapers stop at single players or single clubs. - **Self-healing market value (dual-source)** — every current market value is taken from the page header **and** cross-checked against Transfermarkt's own `ceapi` valuation endpoint. If the website's HTML layout changes, the scraper automatically falls back to the JSON source and keeps working — the field `market_value_source` (`html` / `ceapi` / `html+ceapi`) tells you exactly where each value came from. - **Quality score on every record** — `parse_confidence` (0–1.0) plus machine-readable `warnings` mean you (and your monitoring) instantly see if a page structure drifted, instead of silently getting blanks. - **No start fee** — you pay only for player records actually returned. Runs that hit zero results cost you nothing. - **Peak value + full history + full transfers** — current value, all-time peak (with date), the complete dated valuation history (opt-in), and the complete transfer history (clubs, fees, dates) — all in one record. ### What the Transfermarkt Scraper returns **25+ fields per player record:** | Field | Description | |---|---| | `player_id` | Transfermarkt numeric player ID | | `name` | Player display name | | `full_name` | Name in home country (full legal name) | | `shirt_number` | Squad shirt number | | `current_club` | Current club name | | `league` | League / competition (club mode) | | `position` | Playing position (e.g. "Attack - Right Winger") | | `age` | Age in years | | `date_of_birth` | Date of birth (DD/MM/YYYY) | | `place_of_birth` | City of birth | | `nationality` | List of citizenships | | `height` | Height (e.g. "1,70 m") | | `foot` | Preferred foot | | `market_value` | Current market value, integer EUR | | `market_value_str` | Current market value, display (e.g. "€15.00m") | | `market_value_currency` | Currency symbol (€, £, $, US$) | | `market_value_source` | Where the value came from: `html`, `ceapi`, or `html+ceapi` (both agree) | | `market_value_peak` | All-time peak market value, integer EUR | | `market_value_peak_str` | Peak value, display | | `market_value_peak_date` | Date of the peak value | | `market_value_history` | Full dated valuation history (opt-in: `includeMarketValueHistory`) | | `contract_until` | Contract expiry date | | `agent` | Player agent | | `outfitter` | Boot/kit outfitter | | `profile_url` | Canonical Transfermarkt profile URL | | `image_url` | Player portrait image URL | | `transfers` | Transfer history (from/to club, fee, `fee_type`, date) | | `parse_confidence` | Data quality score (0–1.0) | | `warnings` | List of quality warning codes | | `scraped_at` | ISO-8601 scrape timestamp | Each `transfers[]` entry includes `season`, `date`, `from_club`, `to_club`, `fee` (int EUR), `fee_str`, `fee_type` (`fee` / `free` / `loan` / `end_of_loan` / `unknown`), and `market_value_str`. Each `market_value_history[]` point includes `date`, `value` (int EUR), `value_str`, and `club`. ### How to scrape Transfermarkt market values The actor has five input modes — combine any of them in one run: - **`playerUrls`** — paste profile URLs or bare IDs (e.g. `28003`). Each player gets a full profile scrape with peak market value and complete transfer history. - **`clubUrls`** — paste squad URLs or club IDs (e.g. `131`). Every squad player becomes one record: name, position, market value, age, nationality. - **`leagueCodes`** — paste a competition code or URL (e.g. `GB1` for the Premier League, `ES1` for LaLiga). The scraper walks every member club and returns their full squads, capped by Max Results across the league. **Scrape a whole division in one run.** - **`search`** — free-text player search (e.g. `Haaland`). The top matches are looked up and their profiles scraped. - **`rankings`** — scrape Transfermarkt's most-valuable-players ranking, paginated, up to Max Results. **Common competition codes:** `GB1` Premier League · `ES1` LaLiga · `IT1` Serie A · `L1` Bundesliga · `FR1` Ligue 1 · `MLS1` Major League Soccer · `PO1` Liga Portugal · `NL1` Eredivisie. ### Use cases for Transfermarkt football player data - **Market value tracking** — monitor current and peak market values for any player or squad over time - **Squad analysis** — pull a full club roster with positions, ages, and valuations in one call - **Transfer research** — extract complete transfer history (fees, clubs, dates) for scouting and journalism - **Fantasy football & analytics** — feed player valuations and positions into models and dashboards - **Talent scouting** — rank the most valuable footballers and surface rising young players - **Betting & media** — build datasets of player values, contracts, and nationalities for content and models ### Input example ```json { "playerUrls": ["28003"], "clubUrls": ["131"], "leagueCodes": ["GB1"], "rankings": true, "maxResults": 100, "includeMarketValueHistory": false } ```` ### Pricing Pay Per Event: **€0.003 per player record** (€3.00 per 1,000 results). You only pay for player records actually pushed to the dataset. ### Technical notes - **Transport**: server-rendered HTML via `curl_cffi` chrome impersonation (no Cloudflare challenge), plus two clean Transfermarkt `ceapi` JSON endpoints for market-value peak/history and transfer history. - **Resilient parsing**: structural selectors (`data-header__`, `info-table__content` label/value alternation, `table.items`) — not brittle class names. `parse_confidence` flags silent structure drift. - **Self-healing dual-source market value (fallback plan)**: the current market value is read from the HTML header and cross-checked against the `ceapi` valuation JSON. If the HTML layout drifts, the scraper falls back to the JSON value automatically (`market_value_source: "ceapi"`) so your data pipeline keeps flowing. Disagreements are flagged in `warnings`, never silently merged. - **Anti-bot wall detection**: every HTML response is checked for consent/Cloudflare interstitials and truncated bodies. A blocked page is retried (with proxy rotation when enabled) and, if it can't be recovered, the record is dropped — **you are never charged for an empty or garbage record**. - **Rate limit**: ~1.5s inter-request pacing + automatic backoff on 429/403/503 (3 retries: 10/20/40s). - **Proxy**: optional Apify RESIDENTIAL proxy via `proxyConfiguration` for high-volume runs, billed to the run owner. No external proxy account needed. ### Frequently asked questions **Do I need a Transfermarkt account or API key?** No. The actor reads the same public pages and JSON endpoints the Transfermarkt website itself uses. No authentication is required. **Can I scrape a whole squad at once?** Yes — pass a club URL or ID in `clubUrls`; every squad player becomes one record. **Can I scrape a whole league at once?** Yes — pass a competition code (e.g. `GB1`) or league URL in `leagueCodes`. The scraper walks every club in the league and returns their full squads, capped by Max Results. **Am I charged if a run returns nothing?** No. Pricing is per player record pushed, with no actor-start fee. Blocked or empty pages are dropped without billing. **What is `market_value_source`?** It tells you whether each current market value came from the page HTML (`html`), Transfermarkt's valuation JSON (`ceapi`), or both in agreement (`html+ceapi`). It's how the scraper stays reliable when the website's HTML changes. **Does it return peak market value?** Yes. Profile mode pulls the all-time peak value and its date from Transfermarkt's market-value development data. **What about transfer history?** Profile mode returns the full transfer history list (from club, to club, fee, date) for each player. **Does it work without a proxy?** Yes for standard volumes. For large runs, enable Apify RESIDENTIAL proxy to avoid 429 rate limits. **What does parse\_confidence mean?** 1.0 = all critical fields present. Below 0.5 means the page structure likely changed; check `warnings` for affected fields. ### Disclaimer Transfermarkt is a public website. This **Transfermarkt scraper** accesses publicly available player, club, and market-value pages. No authentication is required and no private data is collected. # Actor input Schema ## `playerUrls` (type: `array`): Transfermarkt player profile URLs (e.g. https://www.transfermarkt.com/lionel-messi/profil/spieler/28003) or bare numeric player IDs (e.g. 28003). Each player profile is scraped with market-value peak and full transfer history. ## `clubUrls` (type: `array`): Transfermarkt club squad URLs (e.g. https://www.transfermarkt.com/fc-barcelona/kader/verein/131) or bare numeric club IDs (e.g. 131). Each squad player becomes one record (name, position, market value, age, nationality). ## `leagueCodes` (type: `array`): Whole-league scraping. Paste competition codes (GB1 = Premier League, ES1 = LaLiga, IT1 = Serie A, L1 = Bundesliga, FR1 = Ligue 1, MLS1 = MLS) or full competition URLs (e.g. https://www.transfermarkt.com/premier-league/startseite/wettbewerb/GB1). Every member club's full squad is scraped, capped by Max Results across the whole league. ## `search` (type: `string`): Free-text player search (e.g. 'Haaland', 'Mbappe'). The top matching players are looked up and their full profiles scraped, up to Max Results. ## `rankings` (type: `boolean`): If enabled, scrape Transfermarkt's most-valuable-players ranking (paginated, 25 per page) up to Max Results. Great for a market overview of the top-valued footballers. ## `maxResults` (type: `integer`): Maximum player records per club / league / rankings / search request. Default 100. Player-URL mode ignores this (one record per URL). ## `includeMarketValueHistory` (type: `boolean`): Profile mode (playerUrls / search) only. Attaches each player's complete market-value history (every dated valuation + club) as market\_value\_history. Adds payload size; off by default. ## `proxyConfiguration` (type: `object`): Optional Apify Proxy. Moderate volumes work proxy-free (curl\_cffi chrome impersonation retrieves Transfermarkt without a Cloudflare challenge). For high-volume runs, enable Apify RESIDENTIAL to avoid 429 rate limits. Billed to the run owner; no external proxy account needed. ## Actor input object example ```json { "playerUrls": [ "28003" ], "rankings": false, "maxResults": 100, "includeMarketValueHistory": false, "proxyConfiguration": { "useApifyProxy": false } } ``` # 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 '' with your token const client = new ApifyClient({ token: '', }); // Prepare Actor input const input = { "playerUrls": [ "28003" ], "maxResults": 100, "proxyConfiguration": { "useApifyProxy": false } }; // Run the Actor and wait for it to finish const run = await client.actor("bovi/transfermarkt-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 '' with your token. client = ApifyClient("") # Prepare the Actor input run_input = { "playerUrls": ["28003"], "maxResults": 100, "proxyConfiguration": { "useApifyProxy": False }, } # Run the Actor and wait for it to finish run = client.actor("bovi/transfermarkt-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 '{ "playerUrls": [ "28003" ], "maxResults": 100, "proxyConfiguration": { "useApifyProxy": false } }' | apify call bovi/transfermarkt-scraper --silent --output-dataset ``` ## MCP server setup ```json { "mcpServers": { "apify": { "command": "npx", "args": [ "mcp-remote", "https://mcp.apify.com/?tools=bovi/transfermarkt-scraper", "--header", "Authorization: Bearer " ] } } } ``` ## OpenAPI specification ```json { "openapi": "3.0.1", "info": { "title": "Transfermarkt Scraper - Player Market Values & Transfers", "description": "Scrape Transfermarkt (transfermarkt.com) football player data: market values, squads, transfers, and rankings. Returns 25+ fields per player — name, club, position, age, nationality, market value (current + peak), contract, agent, and transfer history. No login or API key. Pay per player record.", "version": "0.1", "x-build-id": "idAgHHSgfkUcrOYXG" }, "servers": [ { "url": "https://api.apify.com/v2" } ], "paths": { "/acts/bovi~transfermarkt-scraper/run-sync-get-dataset-items": { "post": { "operationId": "run-sync-get-dataset-items-bovi-transfermarkt-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/bovi~transfermarkt-scraper/runs": { "post": { "operationId": "runs-sync-bovi-transfermarkt-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/bovi~transfermarkt-scraper/run-sync": { "post": { "operationId": "run-sync-bovi-transfermarkt-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": { "playerUrls": { "title": "Player URLs or IDs", "type": "array", "description": "Transfermarkt player profile URLs (e.g. https://www.transfermarkt.com/lionel-messi/profil/spieler/28003) or bare numeric player IDs (e.g. 28003). Each player profile is scraped with market-value peak and full transfer history.", "items": { "type": "string" } }, "clubUrls": { "title": "Club URLs or IDs", "type": "array", "description": "Transfermarkt club squad URLs (e.g. https://www.transfermarkt.com/fc-barcelona/kader/verein/131) or bare numeric club IDs (e.g. 131). Each squad player becomes one record (name, position, market value, age, nationality).", "items": { "type": "string" } }, "leagueCodes": { "title": "League / Competition codes or URLs", "type": "array", "description": "Whole-league scraping. Paste competition codes (GB1 = Premier League, ES1 = LaLiga, IT1 = Serie A, L1 = Bundesliga, FR1 = Ligue 1, MLS1 = MLS) or full competition URLs (e.g. https://www.transfermarkt.com/premier-league/startseite/wettbewerb/GB1). Every member club's full squad is scraped, capped by Max Results across the whole league.", "items": { "type": "string" } }, "search": { "title": "Search Query", "type": "string", "description": "Free-text player search (e.g. 'Haaland', 'Mbappe'). The top matching players are looked up and their full profiles scraped, up to Max Results." }, "rankings": { "title": "Scrape Most-Valuable-Players Rankings", "type": "boolean", "description": "If enabled, scrape Transfermarkt's most-valuable-players ranking (paginated, 25 per page) up to Max Results. Great for a market overview of the top-valued footballers.", "default": false }, "maxResults": { "title": "Max Results", "minimum": 1, "maximum": 10000, "type": "integer", "description": "Maximum player records per club / league / rankings / search request. Default 100. Player-URL mode ignores this (one record per URL).", "default": 100 }, "includeMarketValueHistory": { "title": "Include full market-value history", "type": "boolean", "description": "Profile mode (playerUrls / search) only. Attaches each player's complete market-value history (every dated valuation + club) as market_value_history. Adds payload size; off by default.", "default": false }, "proxyConfiguration": { "title": "Proxy configuration", "type": "object", "description": "Optional Apify Proxy. Moderate volumes work proxy-free (curl_cffi chrome impersonation retrieves Transfermarkt without a Cloudflare challenge). For high-volume runs, enable Apify RESIDENTIAL to avoid 429 rate limits. Billed to the run owner; no external proxy account needed.", "default": { "useApifyProxy": false } } } }, "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 } } } } } } } } } } ```