Gelbe Seiten Scraper

Build and refresh German business lists by category and location from public Gelbe Seiten listings. The Actor exports clean business identity, address, phone, email and website when exposed, rating context, listing URL, the originating query, and retrieval time.

Use it for one-time local market research or repeat the same input on an Apify schedule to refresh a CRM, spreadsheet, or directory dataset.

What does this Gelbe Seiten scraper do?

Provide German business terms such as Zahnarzt, Restaurant, or Klempner and locations such as Berlin, Bremen, Hamburg, Munich, districts, regions, or postal codes. Every term is combined with every location.

You can also provide real gelbeseiten.de/branchen/... search URLs. The Actor reads the server-rendered listings, deduplicates businesses by their source UUID, and optionally visits public profiles for email, structured address, opening hours, coordinates, and richer context.

Who is it for?

• Sales teams building location-specific German lead lists
• Agencies researching local categories and contact coverage
• Market analysts comparing categories across cities
• Directory operators refreshing public business records
• Data teams feeding structured Gelbe Seiten records into a pipeline

Why use this Actor?

• Search many category-location combinations in one run
• Keep stable business IDs and source URLs for repeat comparisons
• Capture contacts only when Gelbe Seiten publicly exposes them
• Choose fast search-card extraction or richer profile enrichment
• Export through the default Apify dataset as JSON, CSV, Excel, XML, or RSS
• Use HTTP extraction with low memory rather than a browser

What data can I extract?

Field	Meaning
businessId	Stable Gelbe Seiten listing UUID
name	Public business name
category, categories	Directory category context
address	Combined public address
streetAddress, postalCode, city, country	Structured profile address when exposed
phone, email, website	Public contacts; nullable when absent
rating, reviewCount	Rating context displayed by the source
openingHours	Public profile opening-hours strings
description	Listing/profile description
latitude, longitude	Public profile coordinates when exposed
listingUrl	Canonical Gelbe Seiten profile URL
query	Search term, location, and exact search URL
retrievedAt, source	ISO retrieval time and gelbeseiten.de provenance

How do I get started?

1. Open the Actor input.
2. Add one or more business categories or keywords.
3. Add one or more German locations.
4. Set the total and per-search limits.
5. Keep profile enrichment on when you need emails or structured fields.
6. Click Start.
7. Open the default dataset and export the records.

A useful first input is:

{
  "searchTerms": ["Zahnarzt"],
  "locations": ["Berlin"],
  "maxItems": 20,
  "extractDetails": true
}

Input reference

Input	Type	Default	Description
searchTerms	string[]	[]	Categories or keywords; German terms work best
locations	string[]	[]	German cities, districts, regions, or postal codes
startUrls	Request[]	[]	Real Gelbe Seiten /branchen/ result URLs
maxItems	integer	100	Maximum unique businesses across the run
maxResultsPerSearch	integer	20	Maximum accepted records per search page
extractDetails	boolean	true	Visit profiles for richer public fields
maxConcurrency	integer	5	Concurrent detail requests, from 1 to 15
maxRequestRetries	integer	2	Transient retries, from 0 to 5
proxyConfiguration	object	none	Optional Apify Proxy configuration

Provide either at least one search URL or both non-empty searchTerms and locations. Unsupported domains and non-search Gelbe Seiten URLs fail validation.

Example output

This shortened record reflects the current output shape:

{
  "businessId": "5f06ccb6-068f-4b36-91a4-63113f066676",
  "name": "Zahnarztpraxis Petra Hartmann",
  "category": "Zahnärzte",
  "address": "Friedelstr. 14, 12047 Berlin",
  "phone": "030 6 24 31 33",
  "email": null,
  "website": "https://www.zahnaerztin-neukoelln.de",
  "rating": 4.9,
  "listingUrl": "https://www.gelbeseiten.de/gsbiz/5f06ccb6-068f-4b36-91a4-63113f066676",
  "query": {
    "searchTerm": "Zahnarzt",
    "location": "Berlin",
    "searchUrl": "https://www.gelbeseiten.de/branchen/zahnarzt/berlin"
  },
  "retrievedAt": "2026-09-11T20:10:00.000Z",
  "source": "gelbeseiten.de"
}

Null means the source did not expose the field for that listing. It is not an extraction error by itself.

How much does it cost to extract Gelbe Seiten businesses?

Pay-per-event pricing includes one Run started charge of $0.00005 per run and one Business listing event for each unique row saved.

Tier	Per business
FREE	$0.001472
BRONZE	$0.00128
SILVER	$0.0009984
GOLD	$0.000768
PLATINUM	$0.000768
DIAMOND	$0.000768

At FREE tier, 10 businesses cost about $0.01477, 50 cost about $0.07365, and 100 cost about $0.14725. Profile enrichment is bundled into the business event; it does not create another charge event. Actual source coverage can be below the requested maximum.

Search and refresh workflows

For a recurring directory refresh, keep the input stable and schedule the Actor daily, weekly, or monthly. Use businessId as the durable comparison key, retrievedAt as the snapshot time, and query to preserve why each business entered the dataset.

Apify datasets are run-specific. Compare exports in your destination system or trigger a webhook after each successful run. The Actor does not claim to maintain an internal history, monitor in the background, or emit change alerts by itself.

Spreadsheet and CRM integrations

• Export the dataset directly to CSV or Excel.
• Use the Apify Google Sheets integration for analyst review.
• Send a webhook to Make, Zapier, n8n, or your own API.
• Map businessId to your external unique key before upserting CRM accounts.
• Keep listingUrl and retrievedAt for source auditing.

JavaScript API example

import { ApifyClient } from 'apify-client';

const client = new ApifyClient({ token: process.env.APIFY_TOKEN });
const run = await client.actor('automation-lab/gelbe-seiten-germany-business-listings').call({
  searchTerms: ['Restaurant'],
  locations: ['Bremen'],
  maxItems: 50,
  extractDetails: true,
});
const { items } = await client.dataset(run.defaultDatasetId).listItems();
console.log(items);

Python API example

from apify_client import ApifyClient

client = ApifyClient("YOUR_APIFY_TOKEN")
run = client.actor("automation-lab/gelbe-seiten-germany-business-listings").call(run_input={
    "searchTerms": ["Klempner"],
    "locations": ["Hamburg", "München"],
    "maxItems": 100,
    "extractDetails": True,
})
items = client.dataset(run["defaultDatasetId"]).list_items().items
print(items)

cURL API example

curl -X POST \
  'https://api.apify.com/v2/acts/automation-lab~gelbe-seiten-germany-business-listings/runs?token=YOUR_APIFY_TOKEN' \
  -H 'content-type: application/json' \
  -d '{"searchTerms":["Zahnarzt"],"locations":["Berlin"],"maxItems":20}'

Do not commit an Apify token into source control. Prefer an environment variable or secret manager.

Use with MCP and AI assistants

Add this Actor to Claude Code through Apify MCP:

claude mcp add --transport http apify \
  "https://mcp.apify.com?tools=automation-lab/gelbe-seiten-germany-business-listings"

Claude Desktop, Cursor, and VS Code setup

Use this equivalent desktop/editor configuration:

{
  "mcpServers": {
    "apify": {
      "type": "http",
      "url": "https://mcp.apify.com?tools=automation-lab/gelbe-seiten-germany-business-listings",
      "headers": { "Authorization": "Bearer YOUR_APIFY_TOKEN" }
    }
  }
}

Example prompts:

• “Find 20 dentists in Berlin and return phones and websites.”
• “Extract the supplied Gelbe Seiten Bremen restaurant search URL.”
• “Build a Hamburg and Munich plumber list with profile enrichment.”

Reliability, limits, and failure behavior

Gelbe Seiten currently returns up to 50 server-rendered cards for one search page, so maxResultsPerSearch is capped at 50. Broader coverage requires multiple meaningful locations or narrower category searches.

The Actor retries transient timeouts, rate limits, and selected server failures. It fails loudly for invalid input, unsupported URLs, non-HTML responses, and recognizable blocked or changed page shapes. If one profile enrichment request fails, the useful search-card record is preserved and a warning is logged.

Direct HTTP is the low-cost default. Configure Apify Proxy when your execution environment cannot access the source. Large query matrices can take longer because every term is combined with every location.

Tips for better results

• Prefer German category names such as Zahnarzt over translations.
• Search districts separately when city-wide results exceed 50.
• Turn extractDetails off for faster name/address/phone snapshots.
• Keep it on when email, structured address, opening hours, or coordinates matter.
• Deduplicate future runs with businessId, not business name.
• Treat absent emails and ratings as normal source coverage differences.

Responsible use and legality

This Actor accesses public business-directory pages. You are responsible for complying with Gelbe Seiten terms, applicable database rights, GDPR, marketing rules, and the laws governing your use. Do not use exported phone or email data for unlawful spam, harassment, or automated decisions about people. Minimize collection, retain provenance, secure exports, and honor applicable deletion or objection requests.

Frequently asked questions

Does it expose every business email?

No. email is populated only when the public Gelbe Seiten profile exposes one. The Actor does not guess, purchase, or infer contact details.

Why did I receive fewer than 50 rows?

The directory can expose fewer matching cards, overlapping searches can resolve to the same businessId, and the global maxItems limit stops the run once reached.

Can I use a Gelbe Seiten URL directly?

Yes. Supply a public https://www.gelbeseiten.de/branchen/... URL in startUrls. Profile URLs are output records, not supported search inputs.

Why did a run fail instead of returning an empty dataset?

Invalid input, blocked pages, and changed upstream HTML are errors. Failing closed prevents an inaccessible page from being mistaken for a real zero-result market.

Is a proxy required?

No for the currently verified direct route. It remains optional for environments that need a different network path.

Related automation-lab Actors

• German Impressum Leads Scraper can enrich supplied German business websites with public statutory imprint fields.
• Apple Maps Business Listings Scraper supports a different source for location-based business discovery.

These are separate sources and workflows; no cross-source matching is performed automatically.