# Gelbe Seiten Scraper - German Business Leads (`xtech/gelbe-seiten-scraper-pro`) Actor

𝗙𝗶𝗻𝗱 𝗚𝗲𝗿𝗺𝗮𝗻 𝗯𝘂𝘀𝗶𝗻𝗲𝘀𝘀 𝗹𝗲𝗮𝗱𝘀. Search Gelbe Seiten by service and location. Export names, categories, addresses, phones, websites, ratings, reviews, and source URLs. Filter by rating or contact availability and deduplicate overlapping searches.

- **URL**: https://apify.com/xtech/gelbe-seiten-scraper-pro.md
- **Developed by:** [Xtech](https://apify.com/xtech) (community)
- **Categories:** Lead generation, Business, Automation
- **Stats:** 2 total users, 1 monthly users, 100.0% runs succeeded, 0 bookmarks
- **User rating**: No ratings yet

## Pricing

from $3.00 / 1,000 business records

This Actor is paid per event. You are not charged for the Apify platform usage, but only a fixed price for specific events.

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

## German Business Lead Finder for Gelbe Seiten

Build a clean, source-traceable list of public German businesses for local market research, territory planning, supplier discovery, and legitimate B2B prospecting.

**Unofficial tool — not affiliated with, endorsed by, or sponsored by Gelbe Seiten.**

Enter the services and places you want to explore—such as *Zahnarzt in Berlin* or *Steuerberater in Köln*. The Actor combines the searches, removes duplicate listings, and gives you an export-ready list of businesses.

### What you get

- Business name, listed category, address, postcode, city, and district
- Public phone number and website when the directory displays them
- Public rating and review count
- Listing description when available
- Source listing and search URLs for auditability
- Contact-availability flags and a transparent record-completeness score

The completeness score measures how many useful public fields were present. It is not a recommendation, credit score, or assessment of a business.

### Quick start

```json
{
  "searches": [
    { "keyword": "Zahnarzt", "location": "Berlin" },
    { "keyword": "Kieferorthopädie", "location": "Potsdam" }
  ],
  "maxResults": 50,
  "deduplicate": true
}
````

### Find more relevant businesses

Use the optional filters to create a more focused research list:

- **Minimum rating** and **minimum review count** for reputation-led research
- **Keep only listings with a phone number** when calling is relevant to your workflow
- **Keep only listings with a website** when you need a public company web presence
- **Remove duplicate businesses** when combining overlapping cities, districts, or services

You can also paste an existing Gelbe Seiten results-page URL when you need to repeat a precise search.

### Typical uses

- Map local competitors, suppliers, or service coverage
- Build a territory list for sales planning
- Identify businesses with public contact channels for account research
- Compare categories, cities, ratings, and review volume
- Export a source-traceable shortlist to CSV, Excel, JSON, or your own workflow

### Use public business data responsibly

This Actor collects information displayed publicly in the directory. It does not verify contact preferences, consent, legal basis, or the suitability of any outreach. Public business contact details can still be personal data. You are responsible for ensuring your collection, storage, enrichment, and any contact comply with applicable law, platform terms, and your organization’s policies. This is not legal advice.

### Tips for reliable results

- Start with 10–25 results to check that a search matches your target market.
- Use a specific service plus a city or district instead of a broad national query.
- Combine related searches in one run; duplicate listings are removed by default.
- Not every directory result shows a website, rating, or phone number—use filters only when those fields are essential.

# Actor input Schema

## `searches` (type: `array`):

Add one or more business type and location pairs. Results from every search are combined into one lead list.

## `searchUrls` (type: `array`):

Advanced option: paste existing Gelbe Seiten result-page URLs. Use this when you have a precise search URL to reuse.

## `maxResults` (type: `integer`):

Maximum number of unique business records to save across all searches. Start small to check relevance.

## `minRating` (type: `number`):

Only save listings with this rating or higher. Leave empty to keep listings without ratings too.

## `minReviewCount` (type: `integer`):

Only save listings with at least this many public reviews.

## `requirePhone` (type: `boolean`):

Exclude results where no public business phone number is displayed.

## `requireWebsite` (type: `boolean`):

Exclude results where no public website link is displayed.

## `deduplicate` (type: `boolean`):

Keep one record when the same listing appears in more than one search.

## `proxyConfiguration` (type: `object`):

Optional. Use a proxy if Gelbe Seiten rate-limits or blocks direct requests.

## Actor input object example

```json
{
  "searches": [
    {
      "keyword": "Zahnarzt",
      "location": "Berlin"
    }
  ],
  "maxResults": 50,
  "minReviewCount": 0,
  "requirePhone": false,
  "requireWebsite": false,
  "deduplicate": true,
  "proxyConfiguration": {
    "useApifyProxy": false
  }
}
```

# Actor output Schema

## `businesses` (type: `string`):

No description

# 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 '<YOUR_API_TOKEN>' with your token
const client = new ApifyClient({
    token: '<YOUR_API_TOKEN>',
});

// Prepare Actor input
const input = {
    "searches": [
        {
            "keyword": "Zahnarzt",
            "location": "Berlin"
        }
    ],
    "proxyConfiguration": {
        "useApifyProxy": false
    }
};

// Run the Actor and wait for it to finish
const run = await client.actor("xtech/gelbe-seiten-scraper-pro").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 '<YOUR_API_TOKEN>' with your token.
client = ApifyClient("<YOUR_API_TOKEN>")

# Prepare the Actor input
run_input = {
    "searches": [{
            "keyword": "Zahnarzt",
            "location": "Berlin",
        }],
    "proxyConfiguration": { "useApifyProxy": False },
}

# Run the Actor and wait for it to finish
run = client.actor("xtech/gelbe-seiten-scraper-pro").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 '{
  "searches": [
    {
      "keyword": "Zahnarzt",
      "location": "Berlin"
    }
  ],
  "proxyConfiguration": {
    "useApifyProxy": false
  }
}' |
apify call xtech/gelbe-seiten-scraper-pro --silent --output-dataset

```

## MCP server setup

```json
{
    "mcpServers": {
        "apify": {
            "command": "npx",
            "args": [
                "mcp-remote",
                "https://mcp.apify.com/?tools=xtech/gelbe-seiten-scraper-pro",
                "--header",
                "Authorization: Bearer <YOUR_API_TOKEN>"
            ]
        }
    }
}

```

## OpenAPI specification

```json
{
    "openapi": "3.0.1",
    "info": {
        "title": "Gelbe Seiten Scraper - German Business Leads",
        "description": "𝗙𝗶𝗻𝗱 𝗚𝗲𝗿𝗺𝗮𝗻 𝗯𝘂𝘀𝗶𝗻𝗲𝘀𝘀 𝗹𝗲𝗮𝗱𝘀. Search Gelbe Seiten by service and location. Export names, categories, addresses, phones, websites, ratings, reviews, and source URLs. Filter by rating or contact availability and deduplicate overlapping searches.",
        "version": "0.3",
        "x-build-id": "coaqeaKrPkwNqMoqo"
    },
    "servers": [
        {
            "url": "https://api.apify.com/v2"
        }
    ],
    "paths": {
        "/acts/xtech~gelbe-seiten-scraper-pro/run-sync-get-dataset-items": {
            "post": {
                "operationId": "run-sync-get-dataset-items-xtech-gelbe-seiten-scraper-pro",
                "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/xtech~gelbe-seiten-scraper-pro/runs": {
            "post": {
                "operationId": "runs-sync-xtech-gelbe-seiten-scraper-pro",
                "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/xtech~gelbe-seiten-scraper-pro/run-sync": {
            "post": {
                "operationId": "run-sync-xtech-gelbe-seiten-scraper-pro",
                "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": {
                    "searches": {
                        "title": "Business searches",
                        "minItems": 1,
                        "maxItems": 25,
                        "type": "array",
                        "description": "Add one or more business type and location pairs. Results from every search are combined into one lead list.",
                        "items": {
                            "type": "object",
                            "properties": {
                                "keyword": {
                                    "title": "Business type or service",
                                    "type": "string",
                                    "description": "For example: Zahnarzt, Steuerberater, Friseur, Restaurant.",
                                    "minLength": 1
                                },
                                "location": {
                                    "title": "City, district, or postcode",
                                    "type": "string",
                                    "description": "For example: Berlin, München Schwabing, 50667 Köln.",
                                    "minLength": 1
                                }
                            },
                            "required": [
                                "keyword",
                                "location"
                            ]
                        }
                    },
                    "searchUrls": {
                        "title": "Gelbe Seiten search URLs",
                        "minItems": 1,
                        "maxItems": 25,
                        "type": "array",
                        "description": "Advanced option: paste existing Gelbe Seiten result-page URLs. Use this when you have a precise search URL to reuse.",
                        "items": {
                            "type": "object",
                            "properties": {
                                "url": {
                                    "title": "Search URL",
                                    "description": "A Gelbe Seiten search-results URL.",
                                    "type": "string"
                                }
                            },
                            "required": [
                                "url"
                            ]
                        }
                    },
                    "maxResults": {
                        "title": "Maximum results",
                        "minimum": 1,
                        "maximum": 500,
                        "type": "integer",
                        "description": "Maximum number of unique business records to save across all searches. Start small to check relevance.",
                        "default": 50
                    },
                    "minRating": {
                        "title": "Minimum rating",
                        "minimum": 0,
                        "maximum": 5,
                        "type": "number",
                        "description": "Only save listings with this rating or higher. Leave empty to keep listings without ratings too."
                    },
                    "minReviewCount": {
                        "title": "Minimum review count",
                        "minimum": 0,
                        "type": "integer",
                        "description": "Only save listings with at least this many public reviews.",
                        "default": 0
                    },
                    "requirePhone": {
                        "title": "Keep only listings with a phone number",
                        "type": "boolean",
                        "description": "Exclude results where no public business phone number is displayed.",
                        "default": false
                    },
                    "requireWebsite": {
                        "title": "Keep only listings with a website",
                        "type": "boolean",
                        "description": "Exclude results where no public website link is displayed.",
                        "default": false
                    },
                    "deduplicate": {
                        "title": "Remove duplicate businesses",
                        "type": "boolean",
                        "description": "Keep one record when the same listing appears in more than one search.",
                        "default": true
                    },
                    "proxyConfiguration": {
                        "title": "Proxy configuration",
                        "type": "object",
                        "description": "Optional. Use a proxy if Gelbe Seiten rate-limits or blocks direct requests."
                    }
                }
            },
            "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
                                    }
                                }
                            }
                        }
                    }
                }
            }
        }
    }
}
```