Gelbe Seiten Scraper - German Yellow Pages Business Directory

Scrape Gelbe Seiten (gelbeseiten.de) — Germany's largest business directory ("Yellow Pages"). Search any business category (Branche) in any German city, town, or postal code and get names, addresses, phone numbers, ratings, opening hours, and websites. Optionally follow through to each business's full profile page for opening hours per weekday, precise coordinates, email, and accepted payment methods. No login, no cookies, no API key required.

What this actor does

• Two modes: search (category + city) and detail (direct business profile URLs)
• 40+ curated categories to pick from, or type any custom Branche
• Sort by relevance, rating, or distance
• Filter by minimum rating, "open now", and search radius up to 50 km
• Full German character support — ä, ö, ü, ß are handled correctly in both input and output
• Rich business profiles — opening hours per weekday, GPS coordinates, email, payment methods, all listed business categories, a business description, photo, and recent customer reviews
• Empty fields are omitted — you only ever see fields that were actually found for a business

Output per business

• businessId, businessRealId — Gelbe Seiten internal listing identifiers
• name — business name
• category — the business's primary listed category
• categories[] — all listed categories (when profile fetched)
• businessTypes[] — schema.org business classification (when profile fetched)
• description — short business description/self-listing text
• rating, reviewCount — average star rating (1-5) and number of reviews
• reviews[] — recent customer reviews with author, date, rating, text (when profile fetched; only fields present on the review are included)
• street, zipCode, city, district, country
• latitude, longitude — precise GPS coordinates (when profile fetched)
• distanceKm — distance from the search center (when a search radius is used)
• isOpenNow, nextOpeningInfo — live open/closed status from the search listing
• openingHours — full weekly schedule keyed by German weekday name (when profile fetched)
• phone, email, website
• paymentMethods[] — accepted payment types (when profile fetched)
• logoUrl — business logo image (from search listing)
• imageUrl — a business photo (when profile fetched and the business has one)
• dateModified — when the listing was last updated on Gelbe Seiten
• searchCategory, searchCity — the category/city you searched for (mode=search)
• sourceUrl — canonical Gelbe Seiten profile URL for the business
• recordType: "business", scrapedAt

Input

Field	Type	Default	Description
mode	string	search	search (category + city) or detail (fetch by URL)
category	string (select)	Klempner	Pick a common category, or custom to use customCategory (mode=search)
customCategory	string	–	Any free-text category, overrides category (mode=search)
city	string	Berlin	City, town, or postal code to search in (mode=search)
sortBy	string (select)	relevanz	relevanz / bewertung (rating) / entfernung (distance)
radiusKm	int	0	Widen the search beyond Gelbe Seiten's own default area for the city, 0-50 km (mode=search)
openNowOnly	boolean	false	Only return businesses currently open
includeRelatedCategories	boolean	false	Broaden results to closely related categories
minRating	int	–	Only keep businesses rated at least this many stars (1-5)
fetchDetails	boolean	false	Also visit each business's profile page for richer data (slower)
businessUrls	array	–	Gelbe Seiten profile URLs to fetch directly (mode=detail)
maxItems	int	50	Hard cap on returned records (1-1000)

Example: search plumbers in Berlin

{
  "mode": "search",
  "category": "Klempner",
  "city": "Berlin",
  "maxItems": 50
}

Example: highest-rated restaurants in Munich, with full profiles

{
  "mode": "search",
  "customCategory": "Restaurant",
  "city": "München",
  "sortBy": "bewertung",
  "fetchDetails": true,
  "minRating": 4,
  "maxItems": 30
}

Example: lawyers open right now within 20 km of Cologne

{
  "mode": "search",
  "category": "Rechtsanwalt",
  "city": "Köln",
  "radiusKm": 20,
  "openNowOnly": true,
  "maxItems": 100
}

Example: fetch specific business profiles

{
  "mode": "detail",
  "businessUrls": [
    { "url": "https://www.gelbeseiten.de/gsbiz/1aea7ffa-a033-49f1-a642-45a8132ae29c" }
  ]
}

Use cases

• Local lead generation — build a prospect list of businesses by trade and city for B2B outreach
• Market research — measure business density and average ratings for a category across German cities
• Directory aggregation — feed structured German business data into your own local-search product
• Competitor mapping — see who else operates in a category and area, with ratings and contact info
• Franchise & site-selection analysis — evaluate service-business coverage across neighborhoods

FAQ

What data source does this actor use? It reads the publicly available search and business-profile pages on gelbeseiten.de, Germany's largest Yellow Pages directory. No account or API key is needed.

Is this affiliated with Gelbe Seiten? No. This is an independent, third-party actor that reads publicly accessible pages.

Why do some businesses have no rating or website? Gelbe Seiten only shows a rating once a business has received at least one review, and only shows a website if the business listed one. Fields with no data are simply omitted from the record rather than shown as empty or null.

What's the difference between category and categories? category is the single category shown on the search-results card. categories (only populated with fetchDetails: true) lists every category the business is registered under on its full profile page.

Can I search by postal code instead of a city name? Yes — the city field accepts German postal codes as well as city/town names.

Does radiusKm replace the city filter? No, it widens it. Setting radiusKm to e.g. 20 returns businesses in and around the specified city within that radius, in addition to the city itself.

Why do I sometimes see results from nearby towns, not just the exact city I searched? Gelbe Seiten's own city search is not strictly bounded to city limits, even with radiusKm left at 0 -- it includes the city's immediate surrounding area by default (this is the live site's own behavior, not something this actor adds). Every result has its own city and distanceKm field, so you can filter to the exact city yourself if you need a hard boundary.

How accurate are the GPS coordinates? latitude/longitude come directly from the business's own Gelbe Seiten profile page (only available with fetchDetails: true in search mode, or always in detail mode).

Why is fetchDetails off by default? Fetching each business's full profile page requires one extra request per result, which is slower. Turn it on when you need opening hours, email, coordinates, payment methods, description, photo, or reviews.

Are reviews[] the full review text? Reviews come straight from the business's own Gelbe Seiten profile page. Gelbe Seiten itself truncates some longer reviews with a trailing "..." in the source page — the actor passes through exactly what the profile page shows, it does not fetch a separate "read more" page per review.