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	Unique new businesses per search, from 1 to 200; 51–200 explicitly enables deeper pagination
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 field was not available from the extracted page. It is not an error by itself; when an individual profile request fails, card-only fields are preserved and enrichment may be partial. reviewCount includes the source's aggregate rating count when a separate review count is not exposed.

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

Default/omitted maxResultsPerSearch stays 20. Values up to 50 use only the initial page. Explicitly request 51–200 to follow the source's public load-more form, for example:

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

Both limits count unique new businesses, not raw cards. The global maxItems cap wins. UUIDs are deduplicated before output slots, profile requests and charges, even within a page. Identical normalized search URLs are fetched once; the first query to accept a business owns its provenance. URL searches run before term-location combinations. Terms/locations are trimmed and lowercased in URLs; relevance and matching belong to Gelbe Seiten, not an exact local keyword filter.

Deep mode retains the source form's actual context. A supplied URL filter must be represented with the same value in that form or the run fails clearly rather than silently dropping it. Search URLs with no verifiable pagination context cannot promise deeper filtered coverage. Exhaustion, an empty page, no new IDs, or a safety limit can return fewer rows; malformed AJAX responses fail the run. No complete-directory or complete-email coverage is promised.

Each unique search uses one initial request and at most 40 load-more requests, each with the source-declared page size (at most 50 cards). A run accepts at most 1000 unique searches and 10000 output businesses. Every request has a 30-second timeout, at most three contained HTTPS redirects and the configured 0–5 transient retries. Details are requested only for accepted rows within the remaining output and charge budget. Run time and Apify's total-charge limit may further bound work.

The Actor retries transient timeouts, rate limits, and selected server failures. It validates input before the start charge and fails loudly for unsupported URLs, wrong content types, blocked pages and changed response shapes. Only an evidenced zero-result page is accepted as a legitimate empty search, including the source's HTTP-404 empty page. Recognized result cards missing a mandatory UUID, name or profile link, and AJAX counts inconsistent with the raw card count, fail the run rather than silently dropping businesses. Duplicate UUIDs and missing optional fields remain valid. Detail redirects and explicit structured profile identities must match the requested UUID; a mismatch never attaches another business's contacts. If profile enrichment fails these checks or exhausts retries, the useful search-card record is preserved, a warning is logged and the partial failure is reported once.

The key-value store record RUN-DIAGNOSTICS and final log expose bounded request, retry, search/page, scanned-card, duplicate, detail-fallback and saved-row counters. These contain no contacts, raw HTML or raw inputs. Check detailFallbacks before relying on complete enrichment.

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.
• Opt into 51–200 per search for deeper city lists; use meaningful districts when more coverage is needed.
• 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.

Dependencies, storage and support

Extraction uses public Gelbe Seiten pages and Apify hosting/storage, with optional Apify Proxy. No AI model or paid external data supplier is used. Required operation costs are included in the listed Actor events; there is no separate supplier payment. Spend tiers follow Apify's qualifying monthly Store spend, not this Actor's row count.

Datasets and RUN-DIAGNOSTICS remain in the run's Apify storage until you delete them or your account's retention policy removes them. No cross-run contact cache or external contact database is maintained. Delete run datasets/KV records in Apify when no longer needed. For problems, open an issue on this Actor's Apify Issues tab with the run link and expected behavior; do not post secrets.

Gelbe Seiten is named only to identify the public source. This Actor is independently maintained by automation-lab and is not affiliated with or endorsed by Gelbe Seiten.

Diagnostic privacy

Failed operations send sanitized diagnostic input, exceptions and Actor/build/run IDs to our private GlitchTip service for repair. Secret fields and URL queries are removed, and reports are retained for 30 days. No external business websites are visited for enrichment.

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 my requested maximum?

The source may be exhausted, pages or searches may overlap, and the global maxItems, charge budget or bounded pagination safety stops can limit output. Values up to 50 deliberately do not request load-more pages.

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.