# Gelbe Seiten Scraper — German Business Directory | $2/1K (`bovi/gelbeseiten-directory`) Actor Scrape Gelbe Seiten (German Yellow Pages) business listings by keyword and city. Returns business name, phone, full address, GPS coordinates, website and category. Ideal for B2B lead generation in Germany. No proxy needed. Pay per result. - **URL**: https://apify.com/bovi/gelbeseiten-directory.md - **Developed by:** [Vitalii Bondarev](https://apify.com/bovi) (community) - **Categories:** Lead generation, Marketing, Business - **Stats:** 2 total users, 1 monthly users, 100.0% runs succeeded, NaN bookmarks - **User rating**: No ratings yet ## Pricing from $2.91 / 1,000 listings 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 ## Gelbe Seiten Scraper — German Business Directory **Pay-per-result: $2.00/1K businesses (phone + GPS coordinates included). No proxy. No monthly fee.** Gelbe Seiten is Germany's largest business directory with 3M+ listings. Get phone, full address, GPS coordinates, opening hours, and website for any local business category in any German city — no proxy needed. Scrape **Gelbe Seiten** (gelbeseiten.de), Germany's largest business directory, for any category and city. Returns complete contact data including phone numbers, full addresses, GPS coordinates, websites, and business category — no proxy required. ### What you get | Field | Description | Coverage | |---|---|---| | `name` | Business display name | 100% | | `phone` | Phone number (German format) | ~85% | | `street` | Street address | ~90% | | `postalCode` | 5-digit postal code | ~90% | | `city` | City name | ~90% | | `lat` / `lng` | GPS coordinates | ~80% | | `website` | Business website URL | ~60% | | `categoryType` | Schema.org type (e.g. Electrician, Restaurant) | ~75% | | `detailUrl` | Canonical Gelbe Seiten listing URL | 100% | | `paymentAccepted` | Payment methods | ~40% | | `openingHours` | Opening hours array | ~50% | | `description` | Business description | ~50% | | `parse_confidence` | Parse quality score (0.0–1.0) | 100% | ### Why this beats the competition | | This actor | Other directory scrapers | |---|---|---| | GPS coordinates (lat/lng) | Yes — 80%+ coverage | No | | Phone from JSON-LD (no click-reveal) | Yes | Often blocked | | Opening hours | Yes | Rarely | | Payment methods | Yes | No | | No proxy needed | Yes | Usually requires proxy | | parse_confidence | Yes | No | | Price | $2.00/1K | $3-5/1K | - **Phone in JSON-LD** — no click-to-reveal, no obfuscation. Phone is directly in `application/ld+json` schema data. - **GPS coordinates** — latitude + longitude for every listing that has it (80%+). Competitor actors return street only. Map all electricians in Berlin to find coverage gaps — GPS enables spatial analysis no other directory actor supports. - **parse_confidence** — every record ships a `parse_confidence` score (0.0–1.0). Below 0.7 is a machine-readable signal that the page structure has drifted — your data pipeline can filter automatically. - **No proxy needed** — Gelbe Seiten serves clean HTML from Apify cloud IPs. Zero COGS. ### How it works 1. `GET /suche//` → initial HTML with ~50 business UUIDs 2. `POST /ajaxsuche` (position offset) → paginate remaining results (up to 500+ for large cities) 3. `GET /gsbiz/` → detail page with `application/ld+json` LocalBusiness schema 4. Extract: name, phone, address, GPS, website, type → push + charge per result ### Input | Parameter | Type | Default | Description | |---|---|---|---| | `category` | string | "elektriker" | German business category keyword | | `city` | string | "berlin" | City to search | | `maxItems` | integer | 50 | Max results (0 = all available) | **Category examples:** elektriker, arzt, restaurant, bäcker, friseur, zahnarzt, klempner, maler, steuerberater, anwalt ### Pricing example Pay-per-result (PPE). Each business record = one event charge. | Run size | Cost | |---|---| | 100 businesses | $0.20 | | 500 businesses | $1.00 | | 1,000 businesses | $2.00 | | 5,000 businesses | $10.00 | No proxy subscription needed — Gelbe Seiten serves clean data without blocking. Zero COGS to the buyer beyond Apify platform usage. ### Output sample ```json { "name": "Elektriker Berlin GmbH", "phone": "030 7 21 50 20", "street": "Unter den Linden 42", "postalCode": "10117", "city": "Berlin", "lat": 52.5170365, "lng": 13.3888599, "website": "https://elektriker-berlin.de", "categoryType": "Electrician", "detailUrl": "https://www.gelbeseiten.de/gsbiz/abc123def456", "parse_confidence": 0.85, "warnings": [] } ```` ### FAQ **Do I need a proxy or API key?** No — Gelbe Seiten serves standard HTML from Apify cloud IPs. No proxy and no API key required. Zero extra cost. **What export formats are available?** JSON, CSV, Excel, and XML — downloadable from the dataset page or via the Apify REST API. **Can I schedule regular runs?** Yes. Use Apify Scheduler (or n8n/Zapier) to run on a cadence and push new results to your CRM, database, or a webhook automatically. **What if the actor returns no results?** Verify your `category` and `city` parameters are valid German keywords used on gelbeseiten.de (lowercase, e.g. `elektriker` not `Elektriker`). Large cities + broad categories (e.g. `arzt`/`berlin`) may have 500+ results — use `maxItems` to limit. ### Use cases - Lead generation for local businesses (phone + address + website) - Market research by category/city - Local SEO competitive analysis - Building contact databases for German cities - Real estate — find services by postal code area ### Use with AI agents (MCP) This scraper is callable as a **tool by AI agents** (Claude Desktop, Cursor, VS Code, n8n, LangGraph, CrewAI, or any MCP-compatible client) via Apify's hosted Model Context Protocol server. An agent uses it to **look up German local businesses with phone numbers, addresses, and GPS coordinates mid-conversation** — e.g. "find electricians in Berlin", "list restaurants in Munich for our outreach", or "get GPS coordinates of all plumbers in Hamburg". Point your MCP client at this tool: ```json { "mcpServers": { "apify": { "command": "npx", "args": [ "mcp-remote", "https://mcp.apify.com/?tools=bovi/gelbeseiten-directory", "--header", "Authorization: Bearer " ] } } } ``` ### Integrations Built for lead-gen and local-sales teams building German business contact lists by category and city — the JSON/dataset output drops into the tools you already run, no glue code: - **n8n / Make / Zapier** — trigger a run or pipe every new dataset item into 500+ apps (Google Sheets, Airtable, Slack, HubSpot, your database) with no code: [n8n](https://docs.apify.com/platform/integrations/n8n), [Make](https://docs.apify.com/platform/integrations/make), [Zapier](https://docs.apify.com/platform/integrations/zapier). - **Webhooks** — fire your own endpoint the moment a run finishes, to push results straight into your pipeline ([docs](https://docs.apify.com/platform/integrations/webhooks)). - **MCP server** — expose this actor as a tool to Claude, Cursor, or any [MCP client](https://mcp.apify.com) so an AI agent can pull this data mid-conversation ([guide](https://blog.apify.com/how-to-use-mcp/)). - **API & SDKs** — fetch the dataset as JSON, CSV, or Excel through the Apify REST API or the Python / JS SDKs. See all [Apify integrations](https://apify.com/integrations). ### Legal note Gelbe Seiten is a public business directory. All data is publicly listed by businesses themselves. Phone numbers and addresses are published for the explicit purpose of being contacted by potential customers. Scraping for legitimate research and lead generation is consistent with the data's intended purpose. ### Limitations - \~15–20% of listings lack phone numbers (they use Gelbe Seiten's internal contact form) - \~20% lack GPS coordinates - Large categories in major cities (e.g. arzt/berlin) may have 500+ results — use `maxItems` to limit - Rate: ~1 req/s for detail pages (polite delay built in) # Actor input Schema ## `category` (type: `string`): Business category to search (German keyword, e.g. elektriker, arzt, restaurant, bäcker). Used as the 'was' (what) search term on Gelbe Seiten. ## `city` (type: `string`): City or region to search in (e.g. berlin, münchen, hamburg, köln). Used as the 'wo' (where) search term. ## `maxItems` (type: `integer`): Maximum number of business listings to return. Each result = one PPE charge ($2/1K). Set 0 for all available results (may be 500+ for large cities). Default: 50. ## Actor input object example ```json { "category": "elektriker", "city": "münchen", "maxItems": 100 } ``` # Actor output Schema ## `results` (type: `string`): Dataset containing Gelbeseiten Directory records (name, phone, street, city, categoryType, website, detailUrl, openingHours, dateModified, parse\_confidence). # 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 = { "category": "elektriker", "city": "berlin", "maxItems": 50 }; // Run the Actor and wait for it to finish const run = await client.actor("bovi/gelbeseiten-directory").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 = { "category": "elektriker", "city": "berlin", "maxItems": 50, } # Run the Actor and wait for it to finish run = client.actor("bovi/gelbeseiten-directory").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 '{ "category": "elektriker", "city": "berlin", "maxItems": 50 }' | apify call bovi/gelbeseiten-directory --silent --output-dataset ``` ## MCP server setup ```json { "mcpServers": { "apify": { "command": "npx", "args": [ "mcp-remote", "https://mcp.apify.com/?tools=bovi/gelbeseiten-directory", "--header", "Authorization: Bearer " ] } } } ``` ## OpenAPI specification ```json { "openapi": "3.0.1", "info": { "title": "Gelbe Seiten Scraper — German Business Directory | $2/1K", "description": "Scrape Gelbe Seiten (German Yellow Pages) business listings by keyword and city. Returns business name, phone, full address, GPS coordinates, website and category. Ideal for B2B lead generation in Germany. No proxy needed. Pay per result.", "version": "0.1", "x-build-id": "RwQRHnEpaBigXO5Am" }, "servers": [ { "url": "https://api.apify.com/v2" } ], "paths": { "/acts/bovi~gelbeseiten-directory/run-sync-get-dataset-items": { "post": { "operationId": "run-sync-get-dataset-items-bovi-gelbeseiten-directory", "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/bovi~gelbeseiten-directory/runs": { "post": { "operationId": "runs-sync-bovi-gelbeseiten-directory", "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/bovi~gelbeseiten-directory/run-sync": { "post": { "operationId": "run-sync-bovi-gelbeseiten-directory", "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": [ "category", "city" ], "properties": { "category": { "title": "Category", "type": "string", "description": "Business category to search (German keyword, e.g. elektriker, arzt, restaurant, bäcker). Used as the 'was' (what) search term on Gelbe Seiten." }, "city": { "title": "City", "type": "string", "description": "City or region to search in (e.g. berlin, münchen, hamburg, köln). Used as the 'wo' (where) search term." }, "maxItems": { "title": "Max results", "minimum": 0, "type": "integer", "description": "Maximum number of business listings to return. Each result = one PPE charge ($2/1K). Set 0 for all available results (may be 500+ for large cities). Default: 50.", "default": 50 } } }, "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 } } } } } } } } } } ```