# Gelbe Seiten Scraper — German Yellow Pages Leads with Emails (`muhammadafzal/gelbe-seiten-scraper`) Actor Scrape German business leads from Gelbe Seiten (gelbeseiten.de) — Yellow Pages Germany. Extract names, phones, decoded emails, websites, addresses, ratings, opening hours, payment methods & GPS coordinates for B2B lead generation in DACH region. Export to CSV, JSON, HubSpot, or integrate via API. - **URL**: https://apify.com/muhammadafzal/gelbe-seiten-scraper.md - **Developed by:** [Muhammad Afzal](https://apify.com/muhammadafzal) (community) - **Categories:** Lead generation, Developer tools - **Stats:** 2 total users, 1 monthly users, 100.0% runs succeeded, 0 bookmarks - **User rating**: No ratings yet ## Pricing from $2.00 / 1,000 business listing (search page)s This Actor is paid per event and usage. You are charged both the fixed price for specific events and for Apify platform usage. 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 ## Gelbe Seiten Scraper — German Yellow Pages Leads 🇩🇪 Scrape **German business leads** from [Gelbe Seiten](https://www.gelbeseiten.de) (gelbeseiten.de), the German Yellow Pages directory. Extract business names, phone numbers, emails, websites, addresses, ratings, opening hours, payment methods, and GPS coordinates for **B2B lead generation, sales prospecting, and market research in Germany**. > Export scraped data, run the scraper via API, schedule and monitor runs, or integrate with other tools. ### Why this actor - **3+ million German businesses** listed across all branches and cities - **Decoded emails** — the only Gelbe Seiten scraper that decodes Cloudflare-protected email addresses - **Structured opening hours** — get a clean `{monday: "07:30–16:30", ...}` object, not raw text - **GPS coordinates** — extract latitude/longitude for mapping and geo-analysis - **Detail-page enrichment** — full descriptions, payment methods, and secondary phone numbers - **Dual input modes** — search by branch + city, or paste direct gelbeseiten.de URLs - **Automatic pagination** — handles the site's `/ajaxsuche` endpoint to walk through thousands of results - **MCP-ready** — semantic field names, structured output, and a tool description optimized for AI agents (Claude, GPT, Cursor) ### Use cases - **B2B lead generation** — build targeted contact lists of German lawyers, doctors, contractors, restaurants, etc. - **Sales prospecting** — enrich CRM records with phone, email, and website data - **Market research** — analyze business density, ratings, and categories by region - **Local SEO** — audit competitor presence across German cities - **Geo-analytics** — map business locations for territory planning ### Input parameters | Field | Type | Required | Default | Description | |---|---|---|---|---| | `searchQuery` | string | No* | `Rechtsanwalt` | What to search for — a German branch, profession, or business type (e.g. `Maler`, `Restaurant`, `Kfz-Werkstatt`). | | `location` | string | No* | `Berlin` | Where to search — a German city, postal code, or region (e.g. `München`, `10115`, `Nordrhein-Westfalen`). | | `startUrls` | array | No | `[]` | Direct `gelbeseiten.de` URLs to scrape instead of search. Accepts search-result and business detail URLs. | | `maxResults` | integer | No | `50` (prefill `3`) | Maximum business records to collect. Pagination handled automatically. | | `scrapeDetailPages` | boolean | No | `true` | Visit each business detail page to extract email, full opening hours, description, payment methods, and GPS. | | `proxyUrl` | string | No | `""` | Optional custom proxy URL (e.g. `http://user:pass@host:port`). Leave empty to use Apify proxies. | \*Either `startUrls` OR both `searchQuery` + `location` are required. ### Output fields Each record in the dataset contains: | Field | Type | Description | |---|---|---| | `businessName` | string | Business or professional name | | `category` | string\|null | Branch / category (e.g. "Rechtsanwälte: Fachanwälte für Steuerrecht") | | `street` | string\|null | Street address | | `postalCode` | string\|null | 5-digit German postal code | | `city` | string\|null | City name | | `district` | string\|null | City district (e.g. "Charlottenburg") | | `phone` | string\|null | Primary phone number | | `phoneSecondary` | string\|null | Secondary phone (from detail page) | | `email` | string\|null | Email address (decoded from Cloudflare protection on detail page) | | `website` | string\|null | Business website URL | | `rating` | number\|null | Star rating (0–5) | | `reviewCount` | number\|null | Total review count | | `openingHours` | object\|null | `{ monday: "...", tuesday: "...", ... sunday: "..." }` | | `openStatus` | string\|null | Current open/closed status text | | `description` | string\|null | Business description ("Über das Unternehmen") | | `paymentMethods` | array\|null | Accepted payment methods (e.g. `["Rechnung","Bar"]`) | | `partnerStatus` | string\|null | Gelbe Seiten partner badge (e.g. "Silber Partner") | | `detailUrl` | string | Full gelbeseiten.de detail page URL | | `latitude` | number\|null | GPS latitude | | `longitude` | number\|null | GPS longitude | | `scrapedAt` | string | ISO 8601 timestamp | | `sourceUrl` | string | Source page URL | ### Pricing This actor uses **Pay-Per-Event** pricing — you only pay for what you get: | Event | Price | When charged | |---|---|---| | Actor Start | $0.00005 | Once per run | | **Search result** | **$0.002** | Per business listing extracted from search results | | **Detail enriched** | **$0.005** | Per business enriched from its detail page (only when `scrapeDetailPages=true`) | #### Cost examples - 100 leads (search only): ~$0.20 - 100 leads (with detail enrichment): ~$0.70 - 1,000 leads (with enrichment): ~$7.00 - 10,000 leads (with enrichment): ~$70.00 ### Quick start #### Via Apify Console 1. Go to the actor page in [Apify Console](https://console.apify.com) 2. Set `searchQuery` = `Rechtsanwalt`, `location` = `Berlin`, `maxResults` = `10` 3. Click **Start** and view results in the **Dataset** tab #### Via API ```bash curl -X POST "https://api.apify.com/v2/acts/muhammadafzal~gelbe-seiten-scraper/runs?token=YOUR_TOKEN" \ -H "Content-Type: application/json" \ -d '{"searchQuery":"Maler","location":"München","maxResults":50,"scrapeDetailPages":true}' ```` #### Via MCP (Claude, Cursor, GPT) Ask your AI agent: > "Find 50 lawyers in Berlin with emails and phone numbers from Gelbe Seiten." The actor is MCP-discoverable with semantic field names and a tool description optimized for agent selection. ### How it works 1. **Search URL construction** — `searchQuery` + `location` are slugified and combined into `gelbeseiten.de/branchen/{query}/{location}`. 2. **SERP extraction** — the initial search page is parsed with Cheerio to extract all visible business listings. 3. **Pagination** — the site's `/ajaxsuche` POST endpoint is called repeatedly (50 results per page) until `maxResults` is reached. 4. **Detail enrichment** — when `scrapeDetailPages=true`, each business detail page (`/gsbiz/{uuid}`) is visited to extract the decoded email, full opening hours object, description, payment methods, and GPS coordinates. 5. **Deduplication** — business UUIDs are tracked in a `seenIds` set to prevent duplicate records across paginated results. ### Limitations - Some businesses do not list an email or website — these fields return `null`. - Email addresses on Gelbe Seiten are protected by Cloudflare email obfuscation; this actor decodes them, but a few may still be `null` if the page uses a different protection method. - GPS coordinates are only available on detail pages and may be `null` for some listings. - Very broad searches (e.g. all businesses in Berlin) can return thousands of results — use `maxResults` to cap run cost. ### Proxy & reliability - Uses Apify's default datacenter proxies with automatic residential fallback. - For aggressive use cases, provide your own residential proxy via `proxyUrl` (compatible with Decodo, Bright Data, IPRoyal). - Session pool with `maxUsageCount: 15` and random request delays prevent rate limiting. - State is persisted to the KV store for migration recovery on Apify. ### Support & feedback If you encounter issues, have feature requests, or want a custom enrichment (e.g. website email scraping, CRM export formats), open an issue on the actor's Apify Console page. Reviews help the actor rank higher in the Apify Store — please leave one if it works for you! # Actor input Schema ## `searchQuery` (type: `string`): What to search for on Gelbe Seiten — a branch, profession, or business type in German. Examples: 'Rechtsanwalt', 'Maler', 'Restaurant', 'Kfz-Werkstatt'. Use this when the user describes a niche or category. Use searchQuery + location together; if the user provides a direct gelbeseiten.de URL instead, leave this empty and use startUrls. ## `location` (type: `string`): Where to search — a German city, postal code, or region. Examples: 'Berlin', 'München', '10115', 'Nordrhein-Westfalen'. Pair with searchQuery. Use startUrls instead if the user provided a complete gelbeseiten.de/branchen/... URL. ## `startUrls` (type: `array`): Direct gelbeseiten.de URLs to scrape instead of using searchQuery + location. Accepts search-result URLs (e.g. https://www.gelbeseiten.de/branchen/rechtsanwalt/berlin) and individual business detail URLs (e.g. https://www.gelbeseiten.de/gsbiz/{uuid}). Use this when the user pastes specific Gelbe Seiten links. Do NOT use for non-gelbeseiten.de URLs. ## `maxResults` (type: `integer`): Maximum number of business records to collect before stopping. The prefill of 3 is for a quick test — raise to 50–500 for production runs. Gelbe Seiten searches can return thousands of results; pagination is handled automatically via the site's /ajaxsuche endpoint. ## `scrapeDetailPages` (type: `boolean`): When enabled, the actor visits each business's detail page (/gsbiz/{uuid}) to extract the email (decoded from Cloudflare protection), full structured opening hours, description, payment methods, secondary phone, and GPS coordinates. Adds ~1 request per business and a separate billing event per enriched record. Disable for fast SERP-only runs. ## `proxyUrl` (type: `string`): Optional HTTP/SOCKS proxy URL for using your own residential proxies instead of Apify's built-in proxies. Format: http://user:pass@host:port. Compatible with Decodo, Bright Data, IPRoyal, and other rotating proxy services. Leave empty to use Apify's default datacenter proxies (residential fallback is automatic). ## Actor input object example ```json { "searchQuery": "Rechtsanwalt", "location": "Berlin", "maxResults": 500, "scrapeDetailPages": true } ``` # Actor output Schema ## `results` (type: `string`): Link to the dataset containing all extracted Gelbe Seiten business leads. # 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 = { "searchQuery": "Rechtsanwalt", "location": "Berlin", "maxResults": 500, "scrapeDetailPages": true }; // Run the Actor and wait for it to finish const run = await client.actor("muhammadafzal/gelbe-seiten-scraper").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 = { "searchQuery": "Rechtsanwalt", "location": "Berlin", "maxResults": 500, "scrapeDetailPages": True, } # Run the Actor and wait for it to finish run = client.actor("muhammadafzal/gelbe-seiten-scraper").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 '{ "searchQuery": "Rechtsanwalt", "location": "Berlin", "maxResults": 500, "scrapeDetailPages": true }' | apify call muhammadafzal/gelbe-seiten-scraper --silent --output-dataset ``` ## MCP server setup ```json { "mcpServers": { "apify": { "command": "npx", "args": [ "mcp-remote", "https://mcp.apify.com/?tools=muhammadafzal/gelbe-seiten-scraper", "--header", "Authorization: Bearer " ] } } } ``` ## OpenAPI specification ```json { "openapi": "3.0.1", "info": { "title": "Gelbe Seiten Scraper — German Yellow Pages Leads with Emails", "description": "Scrape German business leads from Gelbe Seiten (gelbeseiten.de) — Yellow Pages Germany. Extract names, phones, decoded emails, websites, addresses, ratings, opening hours, payment methods & GPS coordinates for B2B lead generation in DACH region. Export to CSV, JSON, HubSpot, or integrate via API.", "version": "1.0", "x-build-id": "tmR7cflcweXlr85NL" }, "servers": [ { "url": "https://api.apify.com/v2" } ], "paths": { "/acts/muhammadafzal~gelbe-seiten-scraper/run-sync-get-dataset-items": { "post": { "operationId": "run-sync-get-dataset-items-muhammadafzal-gelbe-seiten-scraper", "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/muhammadafzal~gelbe-seiten-scraper/runs": { "post": { "operationId": "runs-sync-muhammadafzal-gelbe-seiten-scraper", "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/muhammadafzal~gelbe-seiten-scraper/run-sync": { "post": { "operationId": "run-sync-muhammadafzal-gelbe-seiten-scraper", "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", "properties": { "searchQuery": { "title": "Search Query (What)", "type": "string", "description": "What to search for on Gelbe Seiten — a branch, profession, or business type in German. Examples: 'Rechtsanwalt', 'Maler', 'Restaurant', 'Kfz-Werkstatt'. Use this when the user describes a niche or category. Use searchQuery + location together; if the user provides a direct gelbeseiten.de URL instead, leave this empty and use startUrls." }, "location": { "title": "Location (Where)", "type": "string", "description": "Where to search — a German city, postal code, or region. Examples: 'Berlin', 'München', '10115', 'Nordrhein-Westfalen'. Pair with searchQuery. Use startUrls instead if the user provided a complete gelbeseiten.de/branchen/... URL." }, "startUrls": { "title": "Start URLs", "type": "array", "description": "Direct gelbeseiten.de URLs to scrape instead of using searchQuery + location. Accepts search-result URLs (e.g. https://www.gelbeseiten.de/branchen/rechtsanwalt/berlin) and individual business detail URLs (e.g. https://www.gelbeseiten.de/gsbiz/{uuid}). Use this when the user pastes specific Gelbe Seiten links. Do NOT use for non-gelbeseiten.de URLs.", "items": { "type": "object", "properties": { "url": { "title": "URL", "description": "A gelbeseiten.de search or business detail URL", "type": "string" } } } }, "maxResults": { "title": "Max Results", "minimum": 1, "maximum": 10000, "type": "integer", "description": "Maximum number of business records to collect before stopping. The prefill of 3 is for a quick test — raise to 50–500 for production runs. Gelbe Seiten searches can return thousands of results; pagination is handled automatically via the site's /ajaxsuche endpoint.", "default": 50 }, "scrapeDetailPages": { "title": "Scrape Detail Pages (Enrich)", "type": "boolean", "description": "When enabled, the actor visits each business's detail page (/gsbiz/{uuid}) to extract the email (decoded from Cloudflare protection), full structured opening hours, description, payment methods, secondary phone, and GPS coordinates. Adds ~1 request per business and a separate billing event per enriched record. Disable for fast SERP-only runs.", "default": true }, "proxyUrl": { "title": "Custom Proxy URL (optional)", "type": "string", "description": "Optional HTTP/SOCKS proxy URL for using your own residential proxies instead of Apify's built-in proxies. Format: http://user:pass@host:port. Compatible with Decodo, Bright Data, IPRoyal, and other rotating proxy services. Leave empty to use Apify's default datacenter proxies (residential fallback is automatic)." } } }, "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 } } } } } } } } } } ```