# Transfermarkt — Wrapped API

> **You are on:** `https://api.paywithlocus.com/api` | [llms.txt](https://paywithlocus.com/llms.txt) | [docs](https://docs.paywithlocus.com)
>
> Locus runs on multiple environments -- make sure every URL you call matches your expected environment.
> | Environment | Landing | API | Docs |
> |---|---|---|---|
> | Production | paywithlocus.com | api.paywithlocus.com | docs.paywithlocus.com |
> | Beta | beta.paywithlocus.com | api.beta.paywithlocus.com | docs.paywithlocus.com |
> | Stage | stage.paywithlocus.com | api.stage.paywithlocus.com | docs.paywithlocus.com |
>
> If the API URL above doesn't match your expected environment, re-fetch this file from the correct domain.

> Search Transfermarkt for football players and retrieve detailed player profiles, transfer histories, market value timelines, performance stats, and club squad/club information.

**Category:** Sports | **Website:** [transfermarkt.com/](https://transfermarkt.com/) | **Docs:** [parse.bot/marketplace/9c87e3dd-058c-4641-bba7-f4a7d02322e5/transfermarkt-com-api](https://parse.bot/marketplace/9c87e3dd-058c-4641-bba7-f4a7d02322e5/transfermarkt-com-api)

Pay-per-use API proxy. Each call is automatically billed to your wallet in USDC.

## Access

**Base URL:** `https://api.paywithlocus.com/api/wrapped/parse-transfermarkt-com-api-9c87e3dd/`
**Auth:** `Authorization: Bearer <LOCUS_API_KEY>`

## Endpoints

### get_club_info

Retrieves detailed club information by Transfermarkt club ID. Returns the club's name, short name, abbreviation, country, primary competition, crest image URL, physical location (address, city, coordinates), team colors, and squad composition metrics (squad size, average age, total market value, average market value per player, acquisition cost, top-18 players value). Also includes historical club names if applicable. Club IDs can be found in player profiles, transfer records, or squad listings. Returns stale_input if the club ID is not found.

**Estimated cost:** Metered

| Field | Type | Required | Description |
|-------|------|----------|-------------|
| `club_id` | string | Yes | Transfermarkt club ID (numeric string). Found in player profiles (club_id field), transfer records, or search results. |

```bash
curl -X POST https://api.paywithlocus.com/api/wrapped/parse-transfermarkt-com-api-9c87e3dd/get_club_info \
  -H "Authorization: Bearer YOUR_LOCUS_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"club_id":"<string>"}'
```

### get_club_squad

Retrieves the full current squad roster for a club. Each player entry includes detailed information: full name, age, date of birth, playing position (full and abbreviated), height, preferred foot, nationality, current market value (numeric EUR and display format), contract expiry date, shirt number, portrait image URL, and profile URL. Also returns the club name and total squad market value. Useful for getting all player IDs within a specific club. Club IDs can be found in player profiles or search results.

**Estimated cost:** Metered

| Field | Type | Required | Description |
|-------|------|----------|-------------|
| `club_id` | string | Yes | Transfermarkt club ID (numeric string). Found in player profiles (club_id field), transfer records, or search results. |

```bash
curl -X POST https://api.paywithlocus.com/api/wrapped/parse-transfermarkt-com-api-9c87e3dd/get_club_squad \
  -H "Authorization: Bearer YOUR_LOCUS_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"club_id":"<string>"}'
```

### get_player_market_value_history

Retrieves all historical market value assessments for a player, tracking how their estimated worth has changed over time. Each entry records the assessed value in EUR, the date of assessment, the club the player was at, and the player's age at that time. Also returns the current (most recent) market value separately and a list of all club IDs referenced in the history. Useful for charting a player's value trajectory. Player IDs can be obtained from search_players.

**Estimated cost:** Metered

| Field | Type | Required | Description |
|-------|------|----------|-------------|
| `player_id` | string | Yes | Transfermarkt player ID (numeric string). Obtain from search_players or get_top_market_values. |

```bash
curl -X POST https://api.paywithlocus.com/api/wrapped/parse-transfermarkt-com-api-9c87e3dd/get_player_market_value_history \
  -H "Authorization: Bearer YOUR_LOCUS_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"player_id":"<string>"}'
```

### get_player_page_data

Comprehensive endpoint returning all available data for a player in a single call: full profile (personal details, attributes, market value, club assignments), complete transfer history (all moves with fees and clubs), full market value history (every assessment since tracking began), and current season performance statistics (per-competition goals, assists, appearances). Combines what get_player_profile, get_player_transfers, get_player_market_value_history, and get_player_stats return individually. Useful when you need all player data at once to minimize round-trips. Player IDs can be obtained from search_players.

**Estimated cost:** Metered

| Field | Type | Required | Description |
|-------|------|----------|-------------|
| `player_id` | string | Yes | Transfermarkt player ID (numeric string). Obtain from search_players or get_top_market_values. |

```bash
curl -X POST https://api.paywithlocus.com/api/wrapped/parse-transfermarkt-com-api-9c87e3dd/get_player_page_data \
  -H "Authorization: Bearer YOUR_LOCUS_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"player_id":"<string>"}'
```

### get_player_profile

Retrieves a comprehensive player profile by Transfermarkt player ID. Returns personal details (full name, date of birth, height, nationality, place of birth), playing attributes (position with primary and secondary alternatives, preferred foot), career info (current club assignments with shirt numbers, contract expiry, agent), and market value breakdown (current, previous, highest ever, and delta/change). Player IDs can be obtained from search_players or get_top_market_values. Returns stale_input if the ID does not match any player.

**Estimated cost:** Metered

| Field | Type | Required | Description |
|-------|------|----------|-------------|
| `player_id` | string | Yes | Transfermarkt player ID (numeric string). Obtain from search_players or get_top_market_values. |

```bash
curl -X POST https://api.paywithlocus.com/api/wrapped/parse-transfermarkt-com-api-9c87e3dd/get_player_profile \
  -H "Authorization: Bearer YOUR_LOCUS_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"player_id":"<string>"}'
```

### get_player_stats

Retrieves player performance statistics for the current season. Returns per-competition breakdowns including appearances, goals scored, assists, yellow cards, second yellow cards, red cards, minutes played, start eleven percentage, and goal contribution percentage. Data comes from the performance API and covers all competitions the player has participated in during the current campaign. Also attempts to parse career totals from HTML (may be empty if page structure changes). Player IDs can be obtained from search_players.

**Estimated cost:** Metered

| Field | Type | Required | Description |
|-------|------|----------|-------------|
| `player_id` | string | Yes | Transfermarkt player ID (numeric string). Obtain from search_players or get_top_market_values. |

```bash
curl -X POST https://api.paywithlocus.com/api/wrapped/parse-transfermarkt-com-api-9c87e3dd/get_player_stats \
  -H "Authorization: Bearer YOUR_LOCUS_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"player_id":"<string>"}'
```

### get_player_transfers

Retrieves the complete transfer history for a player, ordered from most recent to earliest. Each transfer record includes source and destination clubs (with names, competition IDs, and country IDs), transfer fee (display string and numeric value when available), market value at the time of transfer, contract end date, age at transfer, and season. Also includes the total fee sum across all transfers. Club names are resolved from IDs. Player IDs can be obtained from search_players.

**Estimated cost:** Metered

| Field | Type | Required | Description |
|-------|------|----------|-------------|
| `player_id` | string | Yes | Transfermarkt player ID (numeric string). Obtain from search_players or get_top_market_values. |

```bash
curl -X POST https://api.paywithlocus.com/api/wrapped/parse-transfermarkt-com-api-9c87e3dd/get_player_transfers \
  -H "Authorization: Bearer YOUR_LOCUS_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"player_id":"<string>"}'
```

### get_referee_info

Retrieves referee profile and career statistics by Transfermarkt referee ID. Returns personal details (name, date of birth with age, citizenship, affiliated club) and officiating statistics broken down by competition: total appearances, yellow cards issued, second yellow cards, red cards, and penalty kicks awarded. Also provides career totals summing all competitions. Data is parsed from the referee profile page.

**Estimated cost:** Metered

| Field | Type | Required | Description |
|-------|------|----------|-------------|
| `referee_id` | string | Yes | Transfermarkt referee ID (numeric string). |

```bash
curl -X POST https://api.paywithlocus.com/api/wrapped/parse-transfermarkt-com-api-9c87e3dd/get_referee_info \
  -H "Authorization: Bearer YOUR_LOCUS_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"referee_id":"<string>"}'
```

### get_top_market_values

Fetches the top 500 most valuable football players worldwide from Transfermarkt's ranking. Results are pre-sorted by descending market value. Internally paginates 20 pages of 25 players each, returning a complete ranked list in one call. Each player includes rank, name, position, age, nationality, current club, market value as display string (e.g. '€200.00m') and as integer euros. No input parameters required — always returns the full top-500 list. Useful for discovering player IDs for use with other endpoints.

**Estimated cost:** Metered

_No parameters required._

```bash
curl -X POST https://api.paywithlocus.com/api/wrapped/parse-transfermarkt-com-api-9c87e3dd/get_top_market_values \
  -H "Authorization: Bearer YOUR_LOCUS_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{}'
```

### search_players

Full-text search for football players by name. Accepts partial or full player names and returns paginated results with 10 players per page. Useful for finding a player's numeric ID which is required by profile, transfers, stats, and market value endpoints. Server handles fuzzy matching — partial strings like 'Mess' will match 'Messi'. Results include basic info: player ID, name, club, position, age, nationality, and market value display string. Results are auto-iterated across pages by the SDK; pass query only.

**Estimated cost:** Metered

| Field | Type | Required | Description |
|-------|------|----------|-------------|
| `page` | integer | No | Page number for paginated results. |
| `query` | string | Yes | Search keyword — player name or partial name. |

```bash
curl -X POST https://api.paywithlocus.com/api/wrapped/parse-transfermarkt-com-api-9c87e3dd/search_players \
  -H "Authorization: Bearer YOUR_LOCUS_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"page":"<integer>","query":"<string>"}'
```