# Transfermarkt Player Market Value & Transfer Scraper (`dataspryva/transfermarkt-player-market-value-and-transfer`) Actor

Look up football players, clubs, and competitions on Transfermarkt. Get player market value history, transfer records, injury logs, club squads, and competition club lists by name or ID.

- **URL**: https://apify.com/dataspryva/transfermarkt-player-market-value-and-transfer.md
- **Developed by:** [Dataspryva](https://apify.com/dataspryva) (community)
- **Categories:** Automation, Developer tools, Other
- **Stats:** 2 total users, 1 monthly users, 100.0% runs succeeded, 0 bookmarks
- **User rating**: No ratings yet

## Pricing

from $0.49 / 1,000 results

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

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

## What's an Apify Actor?

An Actor is a serverless cloud program that runs on the Apify platform. It has two run modes.
In Batch mode, an Actor accepts a well-defined JSON input, performs an action which can take anything from a few seconds to a few hours,
and optionally produces a well-defined JSON output, datasets with results, or files in key-value store.
In Standby mode, an Actor provides a web server which can be used as a website, API, or an MCP server.

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

## How to integrate an Actor?

If asked about integration, you help developers integrate Actors into their projects.
You adapt to their stack and deliver integrations that are safe, well-documented, and production-ready.

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

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

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

# README

## Transfermarkt Player Market Value & Transfer Scraper

Transfermarkt is the reference source for football player valuations and transfer fees. This actor turns its public player, club and competition data into clean JSON records: current and peak market values, the full valuation timeline, career transfers, squad lists and club/competition transfer windows. Start from a name, a Transfermarkt ID or a pasted URL.

No login, API key or proxy is required.

### What you can scrape

| Mode | What it returns | Input |
|---|---|---|
| `searchPlayers` | Player records for a name search | `query` |
| `byPlayerId` | One full player record per player | `playerIds` |
| `transfersPlayer` | One transfer row per career move | `playerIds` |
| `searchClubs` | Club records for a name search | `query` |
| `byClubId` | Club record plus its squad | `clubIds` |
| `transfersClub` | Arrivals, departures and pending moves | `clubIds`, optional `season` |
| `searchCompetitions` | Competition records for a name search | `query` |
| `byCompetitionId` | Club records for every team in a competition | `competitionIds`, optional `season` |
| `transfersCompetition` | Every transfer in a competition | `competitionIds`, optional `season` |
| `byUrl` | Auto-detects player, club and competition URLs | `urls` |

`playerIds`, `clubIds` and `competitionIds` accept either bare IDs/codes or full Transfermarkt URLs (including regional domains and profile, squad or transfers pages). `byUrl` accepts a mixed list of page types.

### Player records

Each player record includes:

- `playerId`, `name`, `fullName`, `shortName`
- `dateOfBirth`, `age`, `placeOfBirth`, `countryOfBirth`
- `nationality` (array), `nationalityIds`
- `position`, `subPosition`, `positionGroup`
- `height`, `heightMeters`, `foot`
- `currentClub`, `currentClubId`, `currentClubUrl`, `currentClubCrestUrl`
- `joinedCurrentClub`, `contractExpires`, `contractOption`
- `shirtNumber`, `isCaptain`, `status`
- `agentName`, `agentId`, `agentVerified`, `outfitter`
- `marketValue`, `marketValueNumeric`, `marketValueCurrency`, `marketValueDate`
- `previousMarketValue`, `previousMarketValueNumeric`
- `highestMarketValue`, `highestMarketValueNumeric`, `highestMarketValueDate`
- `marketValueHistory` - array of `{date, seasonId, season, club, clubId, clubUrl, age, value, valueNumeric, currency, formattedValue}`
- `transfers` - array of `{date, season, fromClub, fromClubId, toClub, toClubId, fee, feeNumeric, feeCurrency, transferType, feeDescription, marketValue, marketValueNumeric, age, isPending, transferUrl}`
- `transferFeeSum`, `transferFeeSumNumeric`
- `absences` - injuries, suspensions and national-team call-ups
- `injuries` - the injury/illness subset, in the legacy `{date, injury, absence}` shape
- `achievements` - trophies and awards
- `profileUrl`, `imageUrl`, `siteName`, `recordType`, `scrapedAt`

### Club, competition and transfer records

Club records include identity, country, league, squad size, average age, foreigners, squad market value, stadium, address, squad and table position where available.

Competition records include country, confederation, current season, total market value and the club list with rank, points and goal difference.

Transfer records include the player, date, season, from/to club and competition IDs, fee text and EUR integer, transfer type, fee description, market value at the time, pending flag and direction (arrival/departure) for club windows.

### Input

| Field | Type | Default | Notes |
|---|---|---|---|
| `mode` | select | `searchPlayers` | One of the 10 modes above |
| `query` | string | `Messi` | Search modes; at least 2 characters |
| `playerIds` | string array | - | Player IDs or URLs |
| `clubIds` | string array | - | Club IDs or URLs |
| `competitionIds` | string array | - | Competition codes or URLs |
| `urls` | string array | - | Mixed player/club/competition URLs for `byUrl` |
| `season` | integer | — | Season start year, e.g. `2025` for 2025/26; club/competition modes. Leave empty for the current season |
| `minMarketValueEur` | integer | - | Keep players at or above this current value |
| `nationality` | string | - | Case-insensitive substring filter |
| `position` | select | Any | Exact position filter |
| `includeMarketValueHistory` | boolean | `true` | Add the valuation timeline |
| `includeTransferHistory` | boolean | `true` | Add career transfers |
| `includeAbsences` | boolean | `true` | Add injuries/suspensions/call-ups |
| `includeAchievements` | boolean | `false` | Add trophies and awards |
| `includeSquad` | boolean | `true` | Add squads to club records; `byClubId` also emits player records |
| `includeCompetitionClubs` | boolean | `true` | Add clubs and table rows to competition records |
| `maxItems` | integer | `50` | 1-1,000 top-level records |

#### Example: three players by name

```json
{
  "mode": "searchPlayers",
  "query": "Messi",
  "maxItems": 3
}
```

#### Example: one player with everything

```json
{
  "mode": "byPlayerId",
  "playerIds": ["28003"],
  "includeAbsences": true,
  "includeAchievements": true
}
```

#### Example: a club transfer window

```json
{
  "mode": "transfersClub",
  "clubIds": ["https://www.transfermarkt.com/manchester-city/startseite/verein/281"],
  "season": 2025,
  "maxItems": 100
}
```

#### Example: auto-detect mixed URLs

```json
{
  "mode": "byUrl",
  "urls": [
    "https://www.transfermarkt.com/erling-haaland/profil/spieler/418560",
    "https://www.transfermarkt.com/premier-league/startseite/wettbewerb/GB1"
  ],
  "maxItems": 5
}
```

### Output example (trimmed)

```json
{
  "recordType": "player",
  "playerId": "28003",
  "name": "Lionel Messi",
  "fullName": "Lionel Andrés Messi Cuccitini",
  "age": 39,
  "nationality": ["Argentina", "Spain"],
  "position": "Right Winger",
  "currentClub": "Inter Miami CF",
  "currentClubId": "69261",
  "marketValue": "€15.00m",
  "marketValueNumeric": 15000000,
  "highestMarketValue": "€180.00m",
  "highestMarketValueNumeric": 180000000,
  "marketValueHistory": [
    {
      "date": "2026-06-02",
      "seasonId": 2025,
      "club": "Inter Miami CF",
      "age": 38,
      "value": 15000000,
      "formattedValue": "€15.00m"
    }
  ],
  "transfers": [
    {
      "date": "2023-07-15",
      "season": "23/24",
      "fromClub": "Paris Saint-Germain",
      "toClub": "Inter Miami CF",
      "fee": "Free Transfer"
    }
  ],
  "profileUrl": "https://www.transfermarkt.com/lionel-messi/profil/spieler/28003",
  "siteName": "Transfermarkt",
  "scrapedAt": "2026-10-27T00:00:00+00:00"
}
```

### FAQ

**Do I need a Transfermarkt account, API key or proxy?**
No. The actor uses Transfermarkt's public football data without credentials and chooses its own transport automatically.

**Where do I find a player, club or competition ID?**
The ID is the number in a Transfermarkt URL (`/profil/spieler/28003`, `/verein/281`) or the code in a competition URL (`/wettbewerb/GB1`). You can paste the whole URL instead.

**Why is a transfer fee missing?**
Transfermarkt only publishes a fee for some moves. Free transfers, loans and undisclosed deals keep their text label, while `feeNumeric` is omitted. Pending moves can have no fee yet.

**What does `season` mean?**
It is the season start year: `2025` means 2025/26. It applies to club squads, club transfer windows, competition tables and competition transfer windows. Player career transfers always cover the full career.

**Why are some market values or club names missing?**
A player may have no current club, a valuation may not have been published yet, or a historical club may be recorded as "without club". Empty fields are omitted rather than sent as null.

**Does `byClubId` return more than one record?**
Yes. It returns the club record first, then one player record per squad member, matching the previous behavior. Set `maxItems` to cap the total.

**Can I scrape several players, clubs or competitions at once?**
Yes. Use the ID/URL arrays, or `byUrl` with a mixed list.

**Are achievements and absences included by default?**
Absences are on by default. Achievements are off because they add one request per player. Both can be toggled.

**How fresh is the data?**
Every run asks Transfermarkt live, so market values, squads and transfer records reflect the site at run time.

### Limitations

- Transfermarkt does not publish a fee for every transfer; the actor never invents one.
- Pending transfers may have no fee or market value yet.
- Absence records mix injuries, suspensions and national-team call-ups; use `isInjury`, `isSuspension` and `isCallUp` to separate them.
- Output is English. Regional Transfermarkt mirrors are accepted as input URLs, but labels are not localized.
- Profile, club and competition URLs are canonical Transfermarkt pages; the site may challenge direct browserless requests, while image URLs load publicly.
- Player season statistics and global ranking/transfer-record lists are not part of this actor.
- Search needs at least two characters.

This actor is not affiliated with Transfermarkt. Use the data responsibly and respect the source's terms.

# Actor input Schema

## `mode` (type: `string`):

Choose a player, club, competition, transfer or auto-detect mode.

## `query` (type: `string`):

Player, club or competition name. Used by the three search modes. At least 2 characters.

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

Transfermarkt player IDs or profile URLs, one per line. Used by player and player-transfer modes.

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

Transfermarkt club IDs or URLs, one per line. Used by club and club-transfer modes.

## `competitionIds` (type: `array`):

Transfermarkt competition codes (e.g. GB1, ES1) or URLs, one per line.

## `urls` (type: `array`):

Player, club or competition URLs for auto-detect mode. Mixing page types is allowed.

## `season` (type: `integer`):

Club and competition modes only. Use 2025 for 2025/26. Leave empty for the current season.

## `minMarketValueEur` (type: `integer`):

Only keep players whose current market value is at least this many euros.

## `nationality` (type: `string`):

Only keep players whose nationality contains this text, e.g. Argentina or Brazil.

## `position` (type: `string`):

Only keep players in this position.

## `includeMarketValueHistory` (type: `boolean`):

Add every valuation Transfermarkt has recorded for each player.

## `includeTransferHistory` (type: `boolean`):

Add each player's career transfers, including fees and clubs.

## `includeAbsences` (type: `boolean`):

Add injuries, suspensions and national-team call-ups for each player.

## `includeAchievements` (type: `boolean`):

Add trophies and awards for each player. Adds one request per player.

## `includeSquad` (type: `boolean`):

Add the current or selected-season squad to club records. byClubId also emits one player record per squad member.

## `includeCompetitionClubs` (type: `boolean`):

Add the club list and table positions to competition records.

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

Stop after this many top-level records.

## Actor input object example

```json
{
  "mode": "searchPlayers",
  "query": "Messi",
  "position": "",
  "includeMarketValueHistory": true,
  "includeTransferHistory": true,
  "includeAbsences": true,
  "includeAchievements": false,
  "includeSquad": true,
  "includeCompetitionClubs": true,
  "maxItems": 3
}
```

# Actor output Schema

## `records` (type: `string`):

Dataset containing all scraped Transfermarkt records.

# 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 = {
    "mode": "searchPlayers",
    "query": "Messi",
    "position": "",
    "includeMarketValueHistory": true,
    "includeTransferHistory": true,
    "includeAbsences": false,
    "includeAchievements": false,
    "includeSquad": true,
    "includeCompetitionClubs": true,
    "maxItems": 3
};

// Run the Actor and wait for it to finish
const run = await client.actor("dataspryva/transfermarkt-player-market-value-and-transfer").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 = {
    "mode": "searchPlayers",
    "query": "Messi",
    "position": "",
    "includeMarketValueHistory": True,
    "includeTransferHistory": True,
    "includeAbsences": False,
    "includeAchievements": False,
    "includeSquad": True,
    "includeCompetitionClubs": True,
    "maxItems": 3,
}

# Run the Actor and wait for it to finish
run = client.actor("dataspryva/transfermarkt-player-market-value-and-transfer").call(run_input=run_input)

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

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

```

## CLI example

```bash
echo '{
  "mode": "searchPlayers",
  "query": "Messi",
  "position": "",
  "includeMarketValueHistory": true,
  "includeTransferHistory": true,
  "includeAbsences": false,
  "includeAchievements": false,
  "includeSquad": true,
  "includeCompetitionClubs": true,
  "maxItems": 3
}' |
apify call dataspryva/transfermarkt-player-market-value-and-transfer --silent --output-dataset

```

## MCP server setup

```json
{
    "mcpServers": {
        "apify": {
            "type": "http",
            "url": "https://mcp.apify.com/?tools=fetch-actor-details,dataspryva/transfermarkt-player-market-value-and-transfer"
        }
    }
}
```

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

## OpenAPI specification

Download the OpenAPI definition: https://api.apify.com/v2/actors/uDm2vSfKpT4iHtZSa/builds/h4HGY7uTguKzaddA5/openapi.json