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.

---

What You Get

• 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.

---

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

Two ways to run it:

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

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

2. Full-directory enumeration (default) — walks the agency directory from the start:

{
    "maxItems": 50
}

Field	Type	Default	Description
agencyIds	array	[]	Specific Transfermarkt agency IDs to fetch directly (the numeric tail of a .../beraterfirma/berater/<id> URL). Leave empty to enumerate the full agency directory instead.
startId	integer	1	Agency ID to begin full-directory enumeration from. Only used when agencyIds is empty.
maxAgencyId	integer	30000	Safety-cap ceiling for full-directory enumeration. 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.
maxItems	integer	10	Maximum number of agency records to return. Keep this low for a test run — a full-directory run with no cap will walk the entire directory.

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

---

Output

{
    "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": ["Thomas Kroth | Executive Director | licensed", "Lukas Pfeifer"],
    "client_count": 25,
    "clients": ["Jonathan Burkardt | 26 | Eintracht Frankfurt | 2030 | €30.00m"],
    "scraped_at": "2026-08-11T13:29:59.315Z"
}

Field	Type	Description
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 strings	Each entry is "Name", "Name | Role", or "Name | Role | licensed" depending on what Transfermarkt shows for that person.
client_count	number	Number of players in clients — the agency's book size.
clients	array of strings	Each entry is "Player | Age | Club | Contract Until | Market Value".
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.

---

Notes

• A full-directory run (no agencyIds, no maxItems cap) covers the whole directory in one pass.
• client_count always equals clients.length for that record.