# Gelbe Seiten Scraper for German Business Leads (`skootle/gelbeseiten-business-leads`) Actor Scrape gelbeseiten.de, the German yellow pages, by trade and city. Get names, addresses, phone numbers, ratings, geo data, and opening hours, plus a market summary of the local competitive landscape per query. Built for lead generation, DACH sales teams, and AI agents. - **URL**: https://apify.com/skootle/gelbeseiten-business-leads.md - **Developed by:** [Skootle](https://apify.com/skootle) (community) - **Categories:** Lead generation, Agents, Automation - **Stats:** 2 total users, 1 monthly users, 100.0% runs succeeded, 0 bookmarks - **User rating**: No ratings yet ## Pricing from $2.10 / 1,000 results This Actor is paid per event. You are not charged for the Apify platform usage, but only a fixed price for specific events. Since this Actor supports Apify Store discounts, the price gets lower the higher subscription plan you have. Learn more: https://docs.apify.com/platform/actors/running/actors-in-store#pay-per-event ## What's an Apify Actor? Actors are a software tools running on the Apify platform, for all kinds of web data extraction and automation use cases. In Batch mode, an Actor accepts a well-defined JSON input, performs an action which can take anything from a few seconds to a few hours, and optionally produces a well-defined JSON output, datasets with results, or files in key-value store. In Standby mode, an Actor provides a web server which can be used as a website, API, or an MCP server. Actors are written with capital "A". ## How to integrate an Actor? If asked about integration, you help developers integrate Actors into their projects. You adapt to their stack and deliver integrations that are safe, well-documented, and production-ready. The best way to integrate Actors is as follows. In JavaScript/TypeScript projects, use official [JavaScript/TypeScript client](https://docs.apify.com/api/client/js.md): ```bash npm install apify-client ``` In Python projects, use official [Python client library](https://docs.apify.com/api/client/python.md): ```bash pip install apify-client ``` In shell scripts, use [Apify CLI](https://docs.apify.com/cli/docs.md): ````bash # MacOS / Linux curl -fsSL https://apify.com/install-cli.sh | bash # Windows irm https://apify.com/install-cli.ps1 | iex ```bash In AI frameworks, you might use the [Apify MCP server](https://docs.apify.com/platform/integrations/mcp.md). If your project is in a different language, use the [REST API](https://docs.apify.com/api/v2.md). For usage examples, see the [API](#api) section below. For more details, see Apify documentation as [Markdown index](https://docs.apify.com/llms.txt) and [Markdown full-text](https://docs.apify.com/llms-full.txt). # README **Need German business leads with phone numbers you can actually call?** This actor pulls structured business records from Gelbe Seiten, the German yellow pages, by trade and city. Run it three ways: type a trade and a city and press Start, schedule it to refresh a lead list weekly, or call it from your CRM pipeline or AI agent through the Apify API. Every run also ships a market summary record that tells you how crowded the local market is before you spend a cent on outreach. ![Gelbe Seiten Scraper for German Business Leads](https://raw.githubusercontent.com/kesjam/skootle-actors-assets/main/heroes/gelbeseiten-business-leads.png) ### TL;DR You give it a `branche` (trade, like `friseur`, `steuerberater`, `zahnarzt`) and an `ort` (city or postcode, like `berlin` or `20095`). You get back one record per business with `name`, `category`, `street`, `postcode`, `city`, `district`, `phone`, `ratingScore`, `reviewCount`, `openingStatus`, `website`, `detailUrl`, and a `fieldCompletenessScore` so you can filter thin records out before they hit your CRM. Turn on `fetchDetails` and each record is enriched from the business detail page with `latitude`, `longitude`, and `openingHours`. Every run also writes one `MARKET_SUMMARY` record: total businesses listed for that search, phone coverage, rating distribution, review volume, and the top rated competitors. That is the part no other Gelbe Seiten scraper ships. The pain it kills: manually copying names and phone numbers out of gelbeseiten.de into a spreadsheet, one listing at a time, with no idea whether you got 50 of 80 or 50 of 800. If this actor saves you an afternoon of copy-paste, please leave a quick review on the [Reviews tab](https://apify.com/skootle/gelbeseiten-business-leads/reviews). Reviews are how small, honest tools get found. ### What does the Gelbe Seiten scraper do? It searches gelbeseiten.de exactly like a person would: `https://www.gelbeseiten.de/suche//`. It then reads every result card, follows the site's own pagination until it has the number of records you asked for, validates every record against a versioned schema, and writes clean JSON to the dataset. No browser, no proxy tricks, no session juggling. Gelbe Seiten serves this data openly, and the actor fetches it the cheap, polite way: plain HTTP. Three things it does that a copy-paste session or a cheaper scraper does not: 1. **It tells you the size of the whole market, not just your page.** The site says how many businesses exist for your search. The market summary reports it, so "50 records captured, 821 available" is a fact you get on run one. 2. **It scores every record.** `fieldCompletenessScore` (0 to 100) tells you how much of the record is filled in. Sort by it, and your outreach list starts with businesses that have a phone, a rating, and a district. 3. **It fails honestly.** If the site returns results and the actor parses zero, the run fails with a snapshot saved for debugging. You will never pay for a green run with an empty dataset. ### Why scrape Gelbe Seiten instead of Google Maps? Google Maps data is expensive to scrape at scale, aggressively defended, and mixes registered businesses with unverified pins. Gelbe Seiten is the registry-grade directory German businesses actually pay to be listed in. Records carry the business's own submitted category, address, and phone number. For DACH lead generation, that means fewer dead numbers and cleaner segmentation by trade. It is also dramatically cheaper to collect, and this actor passes that saving on: the platform cost of a thousand records here is a couple of cents, and pricing starts at $3.00 per 1,000 records. ### Who is this for? - **Lead-gen agencies** building call and mail lists for German SMB niches: dentists in Hamburg, tax advisors in Munich, hair salons in Berlin. - **DACH sales teams** sizing a territory before hiring or planning a route. - **Local service marketplaces** seeding supplier databases city by city. - **AI agents and automations.** Every record carries `agentMarkdown`, a compact, LLM-ready block, and every run writes an `AGENT_BRIEFING` file to the key-value store, so an agent can read one artifact and know what happened. - **Market researchers** who need rating distributions and competitor density per city, which is exactly what the `MARKET_SUMMARY` record contains. ### How do I run it? The prefilled input works out of the box: `friseur` in `berlin`. Press Start and you get 50 hair salons and one market summary in under 15 seconds. ```json { "branche": "steuerberater", "ort": "muenchen", "maxItems": 100, "fetchDetails": false, "emitMarketSummary": true } ```` - `branche`: what to find. German terms work best (`friseur`, `steuerberater`, `zahnarzt`, `elektriker`, `restaurant`). - `ort`: where. City name or postcode. Umlauts are handled, `muenchen` and `mรผnchen` both work. - `maxItems`: how many records. The actor paginates the site until it reaches this number or runs out of results. - `fetchDetails`: visit each business's own Gelbe Seiten page for `latitude`, `longitude`, and `openingHours`. Slower, one extra page fetch per business, and worth it when you need territory maps or call-window planning. - `emitMarketSummary`: on by default. Adds the one landscape record per run. ### What does the output look like? Real rows from this actor's verification runs (Berlin hair salons, July 2026): ```json { "name": "Hair Affair", "category": "Friseure", "street": "Friesenstr. 8", "postcode": "10965", "city": "Berlin", "district": "Kreuzberg", "phone": "030 6 91 90 89", "ratingScore": null, "reviewCount": 0, "openingStatus": "OPEN", "website": null, "detailUrl": "https://www.gelbeseiten.de/gsbiz/dbb0b6e7-fc4d-48ee-8309-909beb906c9c", "fieldCompletenessScore": 90 } ``` ```json { "name": "Ihr Frisรถr Er Sie Es", "category": "Friseure", "street": "Falkenseer Chaussee 31", "postcode": "13583", "city": "Berlin", "district": "Falkenhagener Feld", "phone": "030 3 72 17 23", "ratingScore": 5, "reviewCount": 1, "openingStatus": "OPEN", "detailUrl": "https://www.gelbeseiten.de/gsbiz/..." } ``` And the market summary that came with them: - Gelbe Seiten lists **821** hair salons for Berlin; the run captured the 50 requested. - **95.4%** of captured businesses list a phone number. - **73.8%** carry customer ratings, average **4.69 of 5**, with 260 reviews across the set. - Top rated with 3+ reviews: Salon Buckwitz (5.0 from 38 reviews), Nickel Ingo Friseursalon (5.0 from 25), Bfriends Friseure (5.0 from 19). That last list is a ready-made "who do I have to beat" answer for any local business client, and a "call the ones with zero reviews first" answer for anyone selling reputation management. Every record also carries `agentMarkdown` (the same record as a compact markdown block), `realId` (Gelbe Seiten's own stable UUID for the business, so re-runs dedupe cleanly), `scrapedAt` in ISO 8601, and `schemaVersion` so downstream code can pin what it parses. ### What does it cost? Pricing is per result, tiered by your Apify plan: **$3.00 per 1,000 records** on the free plan, tapering to **$2.10 per 1,000** for GOLD tier subscribers, plus a $0.01 run start fee. A 100-record city list costs about $0.31. A 1,000-record region sweep costs about $3.01 at the top rate. For comparison, hiring a VA to copy 1,000 listings at even two minutes per listing is 33 hours of work. The going rate for German B2B contact records from list brokers is $200 to $500 per 1,000, with no completeness scoring and no market context. Competing Gelbe Seiten actors on Apify charge $1.20 to $5.00 per 1,000 and none of them ship the market summary, the completeness score, or an honest-failure contract. The platform compute cost is on us and it is tiny: this is an HTTP-only actor, no browser, so a 50-record run finishes in about 8 seconds. ### Three workflows buyers actually run **The territory list.** A lead-gen agency signs a client selling salon software. Monday morning: run `friseur` across `berlin`, `hamburg`, `muenchen`, `koeln`, 200 records each, `fetchDetails` on. By lunch there is a geocoded list of 800 salons with phone numbers and call windows from opening hours, sorted by `fieldCompletenessScore` so the first calls hit the fullest records. The market summaries tell the client how many salons each city actually holds, which becomes the retainer conversation for next quarter. **The reputation gap hunt.** An online-marketing freelancer runs `zahnarzt` in `stuttgart` and reads the market summary first: how many dentists carry ratings, what the average is, who leads. Every practice with `reviewCount: 0` in a market where the leaders hold 40+ reviews is a warm prospect for a reviews-management pitch, and the actor just delivered the pitch deck numbers for free. **The scheduled refresh.** A marketplace ops team schedules the actor monthly for their ten seed categories. `realId` keeps deduplication trivial: new IDs are new businesses to onboard, vanished IDs are churn signals worth checking. The `AGENT_BRIEFING` file in the key-value store gets read by an automation that posts a one-line delta to Slack, so nobody opens a dataset unless something moved. ### Frequently asked questions **Which trades and cities work?** Anything Gelbe Seiten covers, which is effectively every registered business category in Germany. Use German terms for `branche`. For `ort`, any German city, town, or postcode works. **How many results can I get per run?** As many as the directory holds for your search. The Berlin hair salon market alone holds 800+. The actor paginates until it reaches `maxItems` or the end of the listings. **Do I get phone numbers?** Yes, phone coverage in our verification runs was above 95% of listings. Phones come from the listing itself, as the business submitted them. **Do I get email addresses?** Gelbe Seiten does not publish email addresses on listing cards, so no. You get website URLs where the business listed one, and the `detailUrl` for every record. **What happens when a search has no results?** You get zero records, a market summary saying the market is empty, and a clean, honest run. If the site itself shows results and the actor parses nothing (for example, after a site redesign), the run **fails** instead of pretending, and saves a debug snapshot so the issue can be fixed fast. **Can my AI agent use this?** Yes, that is a design goal. Records carry `agentMarkdown`, runs write an `AGENT_BRIEFING` markdown file to the key-value store, enums are normalized, dates are ISO 8601, and the schema is versioned. An agent can call the actor through the Apify API, read the briefing, and decide what to do next without custom parsing. **How fresh is the data?** It is scraped live at run time, straight from the directory. Schedule the actor weekly or monthly to keep a lead list current; `realId` makes deduplication across runs trivial. **Is this legal?** The actor reads publicly available business directory listings, the same pages any visitor sees, over plain HTTP at a polite rate. It collects business contact data that companies published specifically to be found and contacted. It does not log in, does not bypass access controls, and does not collect private personal data. If you use the data for outreach, you are responsible for complying with the laws that apply to you, including GDPR and UWG rules on business-to-business contact in Germany. ### What makes this different from the other Gelbe Seiten scrapers? There are several Gelbe Seiten actors on the store. Here is the honest comparison: they return listing rows, and for basic rows they work. This one is built for the step after scraping, which is deciding what to do with the data: - A **per-run market summary** with market size, phone coverage, rating distribution, and rating leaders. No incumbent ships this. - **`fieldCompletenessScore`** on every record, so list quality is measurable, not vibes. - **Agent-grade output**: `agentMarkdown`, `AGENT_BRIEFING`, normalized enums, ISO dates, versioned schema, stable `realId` for dedupe. - **Honest failures**: a run that cannot deliver fails visibly. You do not pay a start fee for an empty green run. - **Detail enrichment mode** with geo coordinates and opening hours when you need them, off by default so the basic run stays fast and cheap. ### More lead and market data from the same shelf If this actor fits your workflow, two siblings are built the same way, with the same output discipline: - [SAM.gov Federal Contracts Scraper](https://apify.com/skootle/sam-gov-federal-contracts): US federal contract opportunities as clean structured leads for government-facing sales. - [Crexi Commercial Real Estate Scraper](https://apify.com/skootle/crexi-commercial-real-estate-scraper): commercial property listings with pricing intel for CRE brokers and investors. - [Clinical Trials Scraper and Pharma Pipeline Data](https://apify.com/skootle/clinical-trials-intel): trial sponsors, phases, and site locations, useful for life-science business development. ### Your feedback shapes this actor Found a bug, a trade that parses oddly, or a field you need that is missing? Please open an issue on the [Issues tab](https://apify.com/skootle/gelbeseiten-business-leads/issues) rather than leaving it in a review, and it gets fixed fast, usually within days. Issues come with run context, which makes the fix faster for you and everyone after you. And if the actor already does what you need, a short review on the [Reviews tab](https://apify.com/skootle/gelbeseiten-business-leads/reviews) genuinely helps other buyers find it. # Actor input Schema ## `branche` (type: `string`): What kind of business to find. German works best. Examples: friseur, steuerberater, zahnarzt, restaurant ## `ort` (type: `string`): Where to search. City name or postcode. Examples: berlin, muenchen, 20095 ## `maxItems` (type: `integer`): How many business records to return. The market summary is computed from these. ## `fetchDetails` (type: `boolean`): Visit each business detail page for geo coordinates, opening hours, keywords, and extra contact data. Slower and costs one extra page fetch per business. ## `emitMarketSummary` (type: `boolean`): Adds one landscape record per run: rating leaders, review volume, category mix, district spread, phone coverage. ## Actor input object example ```json { "branche": "friseur", "ort": "berlin", "maxItems": 50, "fetchDetails": false, "emitMarketSummary": true } ``` # API You can run this Actor programmatically using our API. Below are code examples in JavaScript, Python, and CLI, as well as the OpenAPI specification and MCP server setup. ## JavaScript example ```javascript import { ApifyClient } from 'apify-client'; // Initialize the ApifyClient with your Apify API token // Replace the '' with your token const client = new ApifyClient({ token: '', }); // Prepare Actor input const input = { "branche": "friseur", "ort": "berlin" }; // Run the Actor and wait for it to finish const run = await client.actor("skootle/gelbeseiten-business-leads").call(input); // Fetch and print Actor results from the run's dataset (if any) console.log('Results from dataset'); console.log(`๐Ÿ’พ Check your data here: https://console.apify.com/storage/datasets/${run.defaultDatasetId}`); const { items } = await client.dataset(run.defaultDatasetId).listItems(); items.forEach((item) => { console.dir(item); }); // ๐Ÿ“š Want to learn more ๐Ÿ“–? Go to โ†’ https://docs.apify.com/api/client/js/docs ``` ## Python example ```python from apify_client import ApifyClient # Initialize the ApifyClient with your Apify API token # Replace '' with your token. client = ApifyClient("") # Prepare the Actor input run_input = { "branche": "friseur", "ort": "berlin", } # Run the Actor and wait for it to finish run = client.actor("skootle/gelbeseiten-business-leads").call(run_input=run_input) # Fetch and print Actor results from the run's dataset (if there are any) print("๐Ÿ’พ Check your data here: https://console.apify.com/storage/datasets/" + run["defaultDatasetId"]) for item in client.dataset(run["defaultDatasetId"]).iterate_items(): print(item) # ๐Ÿ“š Want to learn more ๐Ÿ“–? Go to โ†’ https://docs.apify.com/api/client/python/docs/quick-start ``` ## CLI example ```bash echo '{ "branche": "friseur", "ort": "berlin" }' | apify call skootle/gelbeseiten-business-leads --silent --output-dataset ``` ## MCP server setup ```json { "mcpServers": { "apify": { "command": "npx", "args": [ "mcp-remote", "https://mcp.apify.com/?tools=skootle/gelbeseiten-business-leads", "--header", "Authorization: Bearer " ] } } } ``` ## OpenAPI specification ```json { "openapi": "3.0.1", "info": { "title": "Gelbe Seiten Scraper for German Business Leads", "description": "Scrape gelbeseiten.de, the German yellow pages, by trade and city. Get names, addresses, phone numbers, ratings, geo data, and opening hours, plus a market summary of the local competitive landscape per query. Built for lead generation, DACH sales teams, and AI agents.", "version": "0.0", "x-build-id": "RDblo3a34wrrBBmvR" }, "servers": [ { "url": "https://api.apify.com/v2" } ], "paths": { "/acts/skootle~gelbeseiten-business-leads/run-sync-get-dataset-items": { "post": { "operationId": "run-sync-get-dataset-items-skootle-gelbeseiten-business-leads", "x-openai-isConsequential": false, "summary": "Executes an Actor, waits for its completion, and returns Actor's dataset items in response.", "tags": [ "Run Actor" ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/inputSchema" } } } }, "parameters": [ { "name": "token", "in": "query", "required": true, "schema": { "type": "string" }, "description": "Enter your Apify token here" } ], "responses": { "200": { "description": "OK" } } } }, "/acts/skootle~gelbeseiten-business-leads/runs": { "post": { "operationId": "runs-sync-skootle-gelbeseiten-business-leads", "x-openai-isConsequential": false, "summary": "Executes an Actor and returns information about the initiated run in response.", "tags": [ "Run Actor" ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/inputSchema" } } } }, "parameters": [ { "name": "token", "in": "query", "required": true, "schema": { "type": "string" }, "description": "Enter your Apify token here" } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/runsResponseSchema" } } } } } } }, "/acts/skootle~gelbeseiten-business-leads/run-sync": { "post": { "operationId": "run-sync-skootle-gelbeseiten-business-leads", "x-openai-isConsequential": false, "summary": "Executes an Actor, waits for completion, and returns the OUTPUT from Key-value store in response.", "tags": [ "Run Actor" ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/inputSchema" } } } }, "parameters": [ { "name": "token", "in": "query", "required": true, "schema": { "type": "string" }, "description": "Enter your Apify token here" } ], "responses": { "200": { "description": "OK" } } } } }, "components": { "schemas": { "inputSchema": { "type": "object", "required": [ "branche", "ort" ], "properties": { "branche": { "title": "Trade or keyword (Branche)", "type": "string", "description": "What kind of business to find. German works best. Examples: friseur, steuerberater, zahnarzt, restaurant" }, "ort": { "title": "City or area (Ort)", "type": "string", "description": "Where to search. City name or postcode. Examples: berlin, muenchen, 20095" }, "maxItems": { "title": "Max businesses", "minimum": 1, "maximum": 500, "type": "integer", "description": "How many business records to return. The market summary is computed from these.", "default": 50 }, "fetchDetails": { "title": "Fetch detail pages", "type": "boolean", "description": "Visit each business detail page for geo coordinates, opening hours, keywords, and extra contact data. Slower and costs one extra page fetch per business.", "default": false }, "emitMarketSummary": { "title": "Include market summary record", "type": "boolean", "description": "Adds one landscape record per run: rating leaders, review volume, category mix, district spread, phone coverage.", "default": true } } }, "runsResponseSchema": { "type": "object", "properties": { "data": { "type": "object", "properties": { "id": { "type": "string" }, "actId": { "type": "string" }, "userId": { "type": "string" }, "startedAt": { "type": "string", "format": "date-time", "example": "2025-01-08T00:00:00.000Z" }, "finishedAt": { "type": "string", "format": "date-time", "example": "2025-01-08T00:00:00.000Z" }, "status": { "type": "string", "example": "READY" }, "meta": { "type": "object", "properties": { "origin": { "type": "string", "example": "API" }, "userAgent": { "type": "string" } } }, "stats": { "type": "object", "properties": { "inputBodyLen": { "type": "integer", "example": 2000 }, "rebootCount": { "type": "integer", "example": 0 }, "restartCount": { "type": "integer", "example": 0 }, "resurrectCount": { "type": "integer", "example": 0 }, "computeUnits": { "type": "integer", "example": 0 } } }, "options": { "type": "object", "properties": { "build": { "type": "string", "example": "latest" }, "timeoutSecs": { "type": "integer", "example": 300 }, "memoryMbytes": { "type": "integer", "example": 1024 }, "diskMbytes": { "type": "integer", "example": 2048 } } }, "buildId": { "type": "string" }, "defaultKeyValueStoreId": { "type": "string" }, "defaultDatasetId": { "type": "string" }, "defaultRequestQueueId": { "type": "string" }, "buildNumber": { "type": "string", "example": "1.0.0" }, "containerUrl": { "type": "string" }, "usage": { "type": "object", "properties": { "ACTOR_COMPUTE_UNITS": { "type": "integer", "example": 0 }, "DATASET_READS": { "type": "integer", "example": 0 }, "DATASET_WRITES": { "type": "integer", "example": 0 }, "KEY_VALUE_STORE_READS": { "type": "integer", "example": 0 }, "KEY_VALUE_STORE_WRITES": { "type": "integer", "example": 1 }, "KEY_VALUE_STORE_LISTS": { "type": "integer", "example": 0 }, "REQUEST_QUEUE_READS": { "type": "integer", "example": 0 }, "REQUEST_QUEUE_WRITES": { "type": "integer", "example": 0 }, "DATA_TRANSFER_INTERNAL_GBYTES": { "type": "integer", "example": 0 }, "DATA_TRANSFER_EXTERNAL_GBYTES": { "type": "integer", "example": 0 }, "PROXY_RESIDENTIAL_TRANSFER_GBYTES": { "type": "integer", "example": 0 }, "PROXY_SERPS": { "type": "integer", "example": 0 } } }, "usageTotalUsd": { "type": "number", "example": 0.00005 }, "usageUsd": { "type": "object", "properties": { "ACTOR_COMPUTE_UNITS": { "type": "integer", "example": 0 }, "DATASET_READS": { "type": "integer", "example": 0 }, "DATASET_WRITES": { "type": "integer", "example": 0 }, "KEY_VALUE_STORE_READS": { "type": "integer", "example": 0 }, "KEY_VALUE_STORE_WRITES": { "type": "number", "example": 0.00005 }, "KEY_VALUE_STORE_LISTS": { "type": "integer", "example": 0 }, "REQUEST_QUEUE_READS": { "type": "integer", "example": 0 }, "REQUEST_QUEUE_WRITES": { "type": "integer", "example": 0 }, "DATA_TRANSFER_INTERNAL_GBYTES": { "type": "integer", "example": 0 }, "DATA_TRANSFER_EXTERNAL_GBYTES": { "type": "integer", "example": 0 }, "PROXY_RESIDENTIAL_TRANSFER_GBYTES": { "type": "integer", "example": 0 }, "PROXY_SERPS": { "type": "integer", "example": 0 } } } } } } } } } } ```