# Gelbe Seiten Scraper - German Yellow Pages Business Directory (`crawlerbros/gelbeseiten-scraper`) Actor Scrape Gelbe Seiten (German Yellow Pages) business listings. Search by category (Branche) and city (Ort), or fetch full business profiles by URL. Get names, addresses, phone numbers, ratings, opening hours, websites, and more. - **URL**: https://apify.com/crawlerbros/gelbeseiten-scraper.md - **Developed by:** [Crawler Bros](https://apify.com/crawlerbros) (community) - **Categories:** Automation, Lead generation, Developer tools - **Stats:** 2 total users, 1 monthly users, 100.0% runs succeeded, 0 bookmarks - **User rating**: No ratings yet ## Pricing from $3.00 / 1,000 results This Actor is paid per event and usage. You are charged both the fixed price for specific events and for Apify platform usage. 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 Yellow Pages Business Directory Scrape **Gelbe Seiten** (gelbeseiten.de) — Germany's largest business directory ("Yellow Pages"). Search any business category (Branche) in any German city, town, or postal code and get names, addresses, phone numbers, ratings, opening hours, and websites. Optionally follow through to each business's full profile page for opening hours per weekday, precise coordinates, email, and accepted payment methods. No login, no cookies, no API key required. ### What this actor does - **Two modes:** `search` (category + city) and `detail` (direct business profile URLs) - **40+ curated categories** to pick from, or type any custom Branche - **Sort by** relevance, rating, or distance - **Filter by** minimum rating, "open now", and search radius up to 50 km - **Full German character support** — ä, ö, ü, ß are handled correctly in both input and output - **Rich business profiles** — opening hours per weekday, GPS coordinates, email, payment methods, all listed business categories, a business description, photo, and recent customer reviews - **Empty fields are omitted** — you only ever see fields that were actually found for a business ### Output per business - `businessId`, `businessRealId` — Gelbe Seiten internal listing identifiers - `name` — business name - `category` — the business's primary listed category - `categories[]` — all listed categories (when profile fetched) - `businessTypes[]` — schema.org business classification (when profile fetched) - `description` — short business description/self-listing text - `rating`, `reviewCount` — average star rating (1-5) and number of reviews - `reviews[]` — recent customer reviews with `author`, `date`, `rating`, `text` (when profile fetched; only fields present on the review are included) - `street`, `zipCode`, `city`, `district`, `country` - `latitude`, `longitude` — precise GPS coordinates (when profile fetched) - `distanceKm` — distance from the search center (when a search radius is used) - `isOpenNow`, `nextOpeningInfo` — live open/closed status from the search listing - `openingHours` — full weekly schedule keyed by German weekday name (when profile fetched) - `phone`, `email`, `website` - `paymentMethods[]` — accepted payment types (when profile fetched) - `logoUrl` — business logo image (from search listing) - `imageUrl` — a business photo (when profile fetched and the business has one) - `dateModified` — when the listing was last updated on Gelbe Seiten - `searchCategory`, `searchCity` — the category/city you searched for (mode=search) - `sourceUrl` — canonical Gelbe Seiten profile URL for the business - `recordType: "business"`, `scrapedAt` ### Input | Field | Type | Default | Description | |---|---|---|---| | `mode` | string | `search` | `search` (category + city) or `detail` (fetch by URL) | | `category` | string (select) | `Klempner` | Pick a common category, or `custom` to use `customCategory` (mode=search) | | `customCategory` | string | – | Any free-text category, overrides `category` (mode=search) | | `city` | string | `Berlin` | City, town, or postal code to search in (mode=search) | | `sortBy` | string (select) | `relevanz` | `relevanz` / `bewertung` (rating) / `entfernung` (distance) | | `radiusKm` | int | `0` | Widen the search beyond Gelbe Seiten's own default area for the city, 0-50 km (mode=search) | | `openNowOnly` | boolean | `false` | Only return businesses currently open | | `includeRelatedCategories` | boolean | `false` | Broaden results to closely related categories | | `minRating` | int | – | Only keep businesses rated at least this many stars (1-5) | | `fetchDetails` | boolean | `false` | Also visit each business's profile page for richer data (slower) | | `businessUrls` | array | – | Gelbe Seiten profile URLs to fetch directly (mode=detail) | | `maxItems` | int | `50` | Hard cap on returned records (1-1000) | #### Example: search plumbers in Berlin ```json { "mode": "search", "category": "Klempner", "city": "Berlin", "maxItems": 50 } ```` #### Example: highest-rated restaurants in Munich, with full profiles ```json { "mode": "search", "customCategory": "Restaurant", "city": "München", "sortBy": "bewertung", "fetchDetails": true, "minRating": 4, "maxItems": 30 } ``` #### Example: lawyers open right now within 20 km of Cologne ```json { "mode": "search", "category": "Rechtsanwalt", "city": "Köln", "radiusKm": 20, "openNowOnly": true, "maxItems": 100 } ``` #### Example: fetch specific business profiles ```json { "mode": "detail", "businessUrls": [ { "url": "https://www.gelbeseiten.de/gsbiz/1aea7ffa-a033-49f1-a642-45a8132ae29c" } ] } ``` ### Use cases - **Local lead generation** — build a prospect list of businesses by trade and city for B2B outreach - **Market research** — measure business density and average ratings for a category across German cities - **Directory aggregation** — feed structured German business data into your own local-search product - **Competitor mapping** — see who else operates in a category and area, with ratings and contact info - **Franchise & site-selection analysis** — evaluate service-business coverage across neighborhoods ### FAQ **What data source does this actor use?** It reads the publicly available search and business-profile pages on gelbeseiten.de, Germany's largest Yellow Pages directory. No account or API key is needed. **Is this affiliated with Gelbe Seiten?** No. This is an independent, third-party actor that reads publicly accessible pages. **Why do some businesses have no rating or website?** Gelbe Seiten only shows a rating once a business has received at least one review, and only shows a website if the business listed one. Fields with no data are simply omitted from the record rather than shown as empty or null. **What's the difference between `category` and `categories`?** `category` is the single category shown on the search-results card. `categories` (only populated with `fetchDetails: true`) lists every category the business is registered under on its full profile page. **Can I search by postal code instead of a city name?** Yes — the `city` field accepts German postal codes as well as city/town names. **Does `radiusKm` replace the city filter?** No, it widens it. Setting `radiusKm` to e.g. `20` returns businesses in and around the specified city within that radius, in addition to the city itself. **Why do I sometimes see results from nearby towns, not just the exact city I searched?** Gelbe Seiten's own city search is not strictly bounded to city limits, even with `radiusKm` left at `0` -- it includes the city's immediate surrounding area by default (this is the live site's own behavior, not something this actor adds). Every result has its own `city` and `distanceKm` field, so you can filter to the exact city yourself if you need a hard boundary. **How accurate are the GPS coordinates?** `latitude`/`longitude` come directly from the business's own Gelbe Seiten profile page (only available with `fetchDetails: true` in search mode, or always in `detail` mode). **Why is `fetchDetails` off by default?** Fetching each business's full profile page requires one extra request per result, which is slower. Turn it on when you need opening hours, email, coordinates, payment methods, description, photo, or reviews. **Are `reviews[]` the full review text?** Reviews come straight from the business's own Gelbe Seiten profile page. Gelbe Seiten itself truncates some longer reviews with a trailing "..." in the source page — the actor passes through exactly what the profile page shows, it does not fetch a separate "read more" page per review. # Actor input Schema ## `mode` (type: `string`): What to fetch: search a category + city, or fetch full business profiles from direct URLs. ## `category` (type: `string`): Business category to search for. Pick a common category from the list, or choose 'Custom category' and type your own in the field below (mode=search). ## `customCategory` (type: `string`): Free-text Branche/category not in the curated list above, e.g. 'Fensterreinigung' or 'Yoga-Studio' (mode=search). Takes priority over 'Category' when set. ## `city` (type: `string`): German city, town, or postal code to search in, e.g. 'Berlin', 'München', 'Köln', 'Hamburg' (mode=search). ## `sortBy` (type: `string`): How to order search results (mode=search). ## `radiusKm` (type: `integer`): Widen the search beyond Gelbe Seiten's own default area for the city by this radius in kilometers. Leave at 0 to use the site's default (typically the city plus its immediate surrounding area -- Gelbe Seiten city searches are not strictly bounded to city limits even at 0). Every result includes its own 'city' and 'distanceKm' fields so you can filter precisely (mode=search). ## `openNowOnly` (type: `boolean`): Only return businesses that are currently open (mode=search). ## `includeRelatedCategories` (type: `boolean`): Broaden the search to include closely related business categories, not just an exact category match (mode=search). ## `minRating` (type: `integer`): Only keep businesses with at least this star rating (1-5). Businesses without any rating are always kept. ## `fetchDetails` (type: `boolean`): For each search result, also visit its business profile page to collect opening hours per weekday, precise coordinates, email, payment methods, and all listed categories. Slower (mode=search). ## `businessUrls` (type: `array`): Direct Gelbe Seiten business profile URLs to fetch, e.g. https://www.gelbeseiten.de/gsbiz/\. Use the 'sourceUrl' field from search results. ## `maxItems` (type: `integer`): Hard cap on the number of business records to return. ## Actor input object example ```json { "mode": "search", "category": "Klempner", "city": "Berlin", "sortBy": "relevanz", "radiusKm": 0, "openNowOnly": false, "includeRelatedCategories": false, "fetchDetails": false, "businessUrls": [], "maxItems": 50 } ``` # Actor output Schema ## `businesses` (type: `string`): Dataset containing all scraped Gelbe Seiten business listings. # 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 = { "mode": "search", "category": "Klempner", "city": "Berlin", "sortBy": "relevanz", "radiusKm": 0, "openNowOnly": false, "includeRelatedCategories": false, "fetchDetails": false, "businessUrls": [], "maxItems": 50 }; // Run the Actor and wait for it to finish const run = await client.actor("crawlerbros/gelbeseiten-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 = { "mode": "search", "category": "Klempner", "city": "Berlin", "sortBy": "relevanz", "radiusKm": 0, "openNowOnly": False, "includeRelatedCategories": False, "fetchDetails": False, "businessUrls": [], "maxItems": 50, } # Run the Actor and wait for it to finish run = client.actor("crawlerbros/gelbeseiten-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 '{ "mode": "search", "category": "Klempner", "city": "Berlin", "sortBy": "relevanz", "radiusKm": 0, "openNowOnly": false, "includeRelatedCategories": false, "fetchDetails": false, "businessUrls": [], "maxItems": 50 }' | apify call crawlerbros/gelbeseiten-scraper --silent --output-dataset ``` ## MCP server setup ```json { "mcpServers": { "apify": { "command": "npx", "args": [ "mcp-remote", "https://mcp.apify.com/?tools=crawlerbros/gelbeseiten-scraper", "--header", "Authorization: Bearer " ] } } } ``` ## OpenAPI specification ```json { "openapi": "3.0.1", "info": { "title": "Gelbe Seiten Scraper - German Yellow Pages Business Directory", "description": "Scrape Gelbe Seiten (German Yellow Pages) business listings. Search by category (Branche) and city (Ort), or fetch full business profiles by URL. Get names, addresses, phone numbers, ratings, opening hours, websites, and more.", "version": "1.0", "x-build-id": "saUzzerSxCrL7rOdk" }, "servers": [ { "url": "https://api.apify.com/v2" } ], "paths": { "/acts/crawlerbros~gelbeseiten-scraper/run-sync-get-dataset-items": { "post": { "operationId": "run-sync-get-dataset-items-crawlerbros-gelbeseiten-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/crawlerbros~gelbeseiten-scraper/runs": { "post": { "operationId": "runs-sync-crawlerbros-gelbeseiten-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/crawlerbros~gelbeseiten-scraper/run-sync": { "post": { "operationId": "run-sync-crawlerbros-gelbeseiten-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", "required": [ "mode" ], "properties": { "mode": { "title": "Mode", "enum": [ "search", "detail" ], "type": "string", "description": "What to fetch: search a category + city, or fetch full business profiles from direct URLs.", "default": "search" }, "category": { "title": "Category (Branche)", "enum": [ "custom", "Klempner", "Restaurant", "Rechtsanwalt", "Zahnarzt", "Arzt", "Allgemeinarzt", "Friseur", "Hotel", "Elektroinstallation", "Dachdecker", "Maler", "Steuerberater", "Immobilien", "Gartenbau & Landschaftsbau", "Bestatter", "Physiotherapie", "Tierarzt", "Apotheke", "Optiker", "Fahrschule", "Kfz-Werkstatt", "Gebäudereinigung", "Umzugsunternehmen", "Bäckerei", "Metzgerei", "Kosmetikstudio", "Massage", "Fitnessstudio", "Sanitärinstallation", "Heizung & Sanitär", "Schreiner", "Fenster", "Kanalreinigung", "Rohrreinigung", "Kammerjäger", "Logopädie", "Bauunternehmen", "Notar", "Architekt", "Versicherungsmakler", "Nachhilfe" ], "type": "string", "description": "Business category to search for. Pick a common category from the list, or choose 'Custom category' and type your own in the field below (mode=search).", "default": "Klempner" }, "customCategory": { "title": "Custom category (overrides selection above)", "type": "string", "description": "Free-text Branche/category not in the curated list above, e.g. 'Fensterreinigung' or 'Yoga-Studio' (mode=search). Takes priority over 'Category' when set." }, "city": { "title": "City / location (Ort)", "type": "string", "description": "German city, town, or postal code to search in, e.g. 'Berlin', 'München', 'Köln', 'Hamburg' (mode=search).", "default": "Berlin" }, "sortBy": { "title": "Sort order", "enum": [ "relevanz", "bewertung", "entfernung" ], "type": "string", "description": "How to order search results (mode=search).", "default": "relevanz" }, "radiusKm": { "title": "Search radius (km)", "minimum": 0, "maximum": 50, "type": "integer", "description": "Widen the search beyond Gelbe Seiten's own default area for the city by this radius in kilometers. Leave at 0 to use the site's default (typically the city plus its immediate surrounding area -- Gelbe Seiten city searches are not strictly bounded to city limits even at 0). Every result includes its own 'city' and 'distanceKm' fields so you can filter precisely (mode=search).", "default": 0 }, "openNowOnly": { "title": "Open now only", "type": "boolean", "description": "Only return businesses that are currently open (mode=search).", "default": false }, "includeRelatedCategories": { "title": "Include related categories", "type": "boolean", "description": "Broaden the search to include closely related business categories, not just an exact category match (mode=search).", "default": false }, "minRating": { "title": "Minimum rating", "minimum": 1, "maximum": 5, "type": "integer", "description": "Only keep businesses with at least this star rating (1-5). Businesses without any rating are always kept." }, "fetchDetails": { "title": "Fetch full business profiles", "type": "boolean", "description": "For each search result, also visit its business profile page to collect opening hours per weekday, precise coordinates, email, payment methods, and all listed categories. Slower (mode=search).", "default": false }, "businessUrls": { "title": "Business profile URLs (mode=detail)", "type": "array", "description": "Direct Gelbe Seiten business profile URLs to fetch, e.g. https://www.gelbeseiten.de/gsbiz/<id>. Use the 'sourceUrl' field from search results.", "items": { "type": "object", "properties": { "url": { "title": "URL", "type": "string", "description": "Gelbe Seiten business profile URL." } } }, "default": [] }, "maxItems": { "title": "Max items", "minimum": 1, "maximum": 1000, "type": "integer", "description": "Hard cap on the number of business records to return.", "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 } } } } } } } } } } ```