Transfermarkt Football Agency Directory Scraper

Build a directory of football player agencies from Transfermarkt: company identity, address, staff roster, licensing status, and the full list of players each agency represents — with email, phone, and website included on the agencies that have published them.

Or flip one switch and get the people instead: every agent, scout, director and attorney in Transfermarkt's player-agents directory, one row each, with a stable person ID, nationality, FIFA licence status and the agency they belong to — including the agents who belong to no agency at all.

---

Two Modes

Set mode to choose which directory you want. The two return different rows and are meant to be used together — agency_id joins them.

mode	One row per	Use it for
agencies (default)	Agency	Company contact details, licensing, staff list, full client roster
people	Person	A complete, de-duplicated people directory with IDs and nationalities

---

What You Get — Agencies Mode

• Identity: agency name, street, ZIP/city, and country.
• Contact: phone, fax, email, website, and social links — on the agencies that have published them. Many haven't; pair with website-contact-details-scraper or linkedin-bulk-email-finder to cover the rest.
• Licensing: whether the agency has at least one officially licensed agent.
• Staff: every listed employee, with role (e.g. Executive Director, Agent) and individual licensing status where shown.
• Client roster: every player the agency represents, with age, current club, contract expiry, and market value.
• Every field is flattened to plain strings/numbers/booleans for direct use in a spreadsheet or database.

---

What You Get — People Mode

• A stable person ID for every individual, so you can de-duplicate and re-sync without matching on names.
• Everyone in the directory, not just agency staff — including agents who are attached to no agency, who make up about 10% of the list and cannot be reached from the agency side at all.
• Nationality, including dual nationality where Transfermarkt lists more than one.
• Role — Agent, Scout, Owner, Executive Director, Attorney, Head of Scouting, Partner and a dozen more.
• FIFA licence status per person, and whether their agency is Transfermarkt-verified.
• Name split into surname and given name, alongside the name as listed.
• The agency link — agency_id, name, and the same profile URL agencies mode returns, so the two datasets join exactly.

---

Who Uses This

• Sports agencies and player representatives — map the competitive landscape: who represents whom, and where.
• Cold-outreach and business-development teams — build a prospect list of football agencies, then chain into a contact-enrichment actor for the ones missing published details.
• Journalists and analysts — trace which agency represents a given roster of players, and how large each agency's book is.
• Recruiters and scouts — find the right agency contact for a client relationship.

---

Input

1. Full agency directory (default) — walks the agency directory from the start:

{
    "mode": "agencies",
    "maxItems": 50
}

2. Direct lookup — you already know which agencies you want:

{
    "mode": "agencies",
    "agencyIds": ["12", "2048"],
    "maxItems": 10
}

3. The people directory — every agent, scout and director, one row each:

{
    "mode": "people",
    "maxItems": 100
}

Field	Type	Default	Description
mode	string	"agencies"	"agencies" for company records, "people" for one row per individual.
maxItems	integer	10	Maximum number of records to return. Keep this low for a test run — an uncapped run returns the whole directory.
agencyIds	array	[]	Agencies mode only. Specific Transfermarkt agency IDs to fetch directly (the numeric tail of a .../beraterfirma/berater/<id> URL). Leave empty to walk the full agency directory instead.
startId	integer	1	Agencies mode only. Agency ID to begin the full walk from. Only used when agencyIds is empty.
maxAgencyId	integer	30000	Agencies mode only. Safety-cap ceiling for the full walk. The crawl stops on its own well before this cap once it runs into a long stretch of unassigned IDs — raise it only if you want to push further.

Find an agency ID by opening its Transfermarkt profile — it's the number at the end of the URL (.../beraterfirma/berater/2048 → 2048).

agencyIds, startId and maxAgencyId are ignored in people mode: that directory is walked in full, in one pass.

---

Output — Agencies Mode

{
    "record_type": "agency",
    "agency_id": "12",
    "agency_name": "PRO Profil GmbH",
    "profile_url": "https://www.transfermarkt.com/-/beraterfirma/berater/12",
    "street": "Hörder Burgstr. 18",
    "zip_location": "44263, Dortmund",
    "country": "Germany",
    "phone": "0231 9410920",
    "fax": null,
    "email": "info@proprofil.de",
    "website": "http://www.proprofil.de",
    "social_links": [],
    "is_licensed": true,
    "staff": [
      { "name": "Thomas Kroth", "role": "Executive Director", "is_licensed": true },
      { "name": "Lukas Pfeifer", "role": null, "is_licensed": false }
    ],
    "client_count": 204,
    "clients": [
      { "player": "Jonathan Burkardt", "age": 26, "club": "Eintracht Frankfurt", "contract_until": "2030", "market_value": "€30.00m" }
    ],
    "scraped_at": "2026-08-11T13:29:59.315Z"
}

Field	Type	Description
record_type	string	"agency" — tells the two modes' rows apart if you merge the datasets.
agency_id	string	Transfermarkt agency ID.
agency_name	string	Agency (or individual agent) name.
profile_url	string	Canonical Transfermarkt profile URL.
street	string or null	Street address, when published.
zip_location	string or null	"ZIP, city" as shown on Transfermarkt, when published.
country	string or null	Registered country, when published.
phone	string or null	Phone number, when published.
fax	string or null	Fax number, when published.
email	string or null	Contact email, when published.
website	string or null	Agency website, when published.
social_links	array of strings	Social profile URLs, when published.
is_licensed	boolean	Whether at least one agent at the company is officially licensed.
staff	array of objects	One object per person: name (string), role (string or null), is_licensed (boolean).
client_count	number	Number of players in clients — the agency's full book size.
clients	array of objects	One object per player: player (string), age (number or null), club (string or null), contract_until (string or null), market_value (string or null). The whole roster: Transfermarkt paginates it at 25 players per page and the scraper follows every page.
scraped_at	string	ISO-8601 timestamp of when the record was captured.

A field reads null when Transfermarkt has not filled it in — not when the scraper failed to find it.

---

Output — People Mode

{
    "record_type": "agent",
    "person_id": "15",
    "name": "Kroth, Thomas",
    "name_last": "Kroth",
    "name_first": "Thomas",
    "nationalities": ["Germany"],
    "role": "Executive Director",
    "fifa_licensed": true,
    "agency_id": "12",
    "agency_name": "PRO Profil GmbH",
    "agency_verified": true,
    "agency_url": "https://www.transfermarkt.com/-/beraterfirma/berater/12",
    "person_url": "https://www.transfermarkt.com/berater/spielerberateruebersicht",
    "scraped_at": "2026-09-21T13:29:59.315Z"
}

Field	Type	Description
record_type	string	"agent" — tells the two modes' rows apart if you merge the datasets.
person_id	string	Transfermarkt's own ID for the person. Stable and unique across the directory — use it as your join key, not the name.
name	string	Name as the directory lists it, "Last, First".
name_last	string	Surname, split from name on the first comma.
name_first	string or null	Given name(s). null for the 0.2% of entries the source gives as a single token.
nationalities	array of strings	Country names. Usually one; two or more for dual nationals. Empty when Transfermarkt has none on file (about 18% of the directory).
role	string or null	Function — Agent, Scout, Owner, Executive Director, Attorney, Head of Scouting, Partner, Player Service and others. null when unlisted, which is about a quarter of the directory.
fifa_licensed	boolean	Whether this person carries the officially licensed badge.
agency_id	string or null	The agency they belong to. null for agents attached to no agency.
agency_name	string or null	That agency's name, or null.
agency_verified	boolean or null	Whether that agency carries Transfermarkt's verified badge — about 44% of agency-attached people. null for agents with no agency.
agency_url	string or null	That agency's profile URL — the exact string agencies mode returns as profile_url, so the two datasets join on it directly.
person_url	string	The directory page this person is listed on. Transfermarkt publishes no individual agent profile page, so this is the page where their entry appears.
scraped_at	string	ISO-8601 timestamp of when the record was returned.

Rows come back ordered by person_id, so a capped run always returns the same window and a full run is reproducible.

---

Joining the Two

Run each mode once, then join on agency_id:

• people.agency_id → agencies.agency_id gives you every person with their agency's address, phone, email and website.
• People with agency_id: null have no agency row by definition — they are independent agents, and they only appear in people mode.
• people.agency_url and agencies.profile_url are the same string, if you prefer to join on the URL.

---

Notes

• A full-directory run (no agencyIds, no maxItems cap) covers the whole directory in one pass, in either mode.
• client_count always equals clients.length for that record.
• Large agencies return large rosters — the biggest in the directory carries over 500 players across 22 pages of Transfermarkt's own pagination, all of it in one record.
• People mode is much faster than agencies mode: the whole people directory comes back in minutes, where a complete agency pull is a long run. Cap maxItems on your first agencies run; you rarely need to on a people run.
• People mode does not return player or client rosters. If you want who-represents-whom, that is agencies mode's clients field.