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

Scrape Gelbe Seiten business listings with names, phones, emails, websites, addresses, ratings, and structured German local leads.

- **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 web data automations that power AI and operations. They run on the Apify platform to scrape websites, process data, connect APIs, and automate workflows.
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.

- **AI agents and MCP clients** — the [Apify MCP server](https://docs.apify.com/integrations/mcp.md) at `https://mcp.apify.com` (remote, streamable HTTP, OAuth on first use).
- **Agentic workflows and local Actor development** — [Agent Skills](https://apify.com/.well-known/agent-skills/index.json) with the [Apify CLI](https://docs.apify.com/cli/docs.md): `npm install -g apify-cli`, then `apify login`.
- **JavaScript/TypeScript projects** — the official [JS/TS client](https://docs.apify.com/api/client/js/docs.md): `npm install apify-client`.
- **Python projects** — the official [Python client](https://docs.apify.com/api/client/python/docs.md): `pip install apify-client`.
- **Any other language** — 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 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!

### What is Gelbe Seiten Scraper?

**Gelbe Seiten Scraper** turns the target data into structured, reusable results on Apify. Use it when you need repeatable collection for sales teams, agencies, recruiters, market researchers, and data-enrichment workflows without maintaining a custom scraper or one-off integration. Run it manually, schedule recurring jobs, call it through the Apify API, or connect it to an AI agent through the Apify MCP server.

The Actor stores results in an Apify dataset, where they can be previewed and exported as JSON, CSV, Excel, XML, or RSS. Availability and completeness depend on the source, supplied inputs, public visibility, authentication requirements, and upstream rate limits.

### Use cases for Gelbe Seiten Scraper

- Build structured datasets for research, reporting, enrichment, or monitoring.
- Automate repetitive collection with schedules, webhooks, and API calls.
- Feed clean records into spreadsheets, databases, CRMs, BI tools, AI agents, or RAG pipelines.
- Track changes over time by running the same validated input on a schedule.
- Replace fragile manual copy-and-paste work with a reproducible Apify workflow.

### How to use Gelbe Seiten Scraper

1. Open the Actor input page and choose a focused, valid target.
2. Set a conservative result limit for the first run.
3. Start the Actor and inspect the dataset for coverage and field availability.
4. Export the results or connect the dataset to your downstream system.
5. Scale gradually and use scheduling, pagination, or proxies when supported.

#### Important input options

- `searchQuery` — 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 ni
- `location` — 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 co
- `startUrls` — 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 busines
- `maxResults` — 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 resul
- `scrapeDetailPages` — 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 meth
- `proxyUrl` — 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, an

### API and automation example

```javascript
import { ApifyClient } from 'apify-client';

const client = new ApifyClient({ token: process.env.APIFY_TOKEN });
const run = await client.actor('muhammadafzal/gelbe-seiten-scraper').call({
  // Add the same input fields you use in the Apify Console.
});
const { items } = await client.dataset(run.defaultDatasetId).listItems();
console.log(items);
```

### Related Apify Actors

Use these dedicated tools when a neighboring data source or workflow is a better match:

- [Leads Finder Pro - B2B Leads with Emails \[Apollo Alternative\]](https://apify.com/muhammadafzal/leads-finder-pro)
- [Yellow Pages US Scraper — Business Leads & Reviews](https://apify.com/muhammadafzal/yellow-pages-us-scraper)
- [Yellow Pages Australia Scraper — Business Leads & Reviews](https://apify.com/muhammadafzal/yellow-pages-au-scraper)
- [Email Validator — Syntax, MX & Risk Checks](https://apify.com/muhammadafzal/email-address-validator)
- [Texas State Licensed Contractor Scraper — TDLR License Data](https://apify.com/muhammadafzal/tdlr-texas-scraper)
- [California CSLB Contractor License Scraper](https://apify.com/muhammadafzal/cslb-california-scraper)
- [Instagram Followers & Following Scraper — With Cookies](https://apify.com/muhammadafzal/instagram-following-scraper)
- [Facebook Ads Library Scraper — Meta Ad Intelligence Tool](https://apify.com/muhammadafzal/facebook-ads-library-scraper)
- [Justia Lawyer Directory Scraper — Attorney Leads](https://apify.com/muhammadafzal/justia-lawyer-directory-scraper)
- [OpenTable Restaurants, Ratings & Reviews Scraper](https://apify.com/muhammadafzal/opentable-scraper)

### Frequently asked questions

#### How many results can I scrape with Gelbe Seiten Scraper?

The practical total depends on the source, input limits, pagination, available records, run timeout, and upstream restrictions. Start with a small run, verify the output, and increase the limit gradually.

#### Can I integrate Gelbe Seiten Scraper with other apps?

Yes. Use Apify integrations, webhooks, schedules, dataset exports, Make, Zapier, Google Sheets, cloud storage, or your own application.

#### Can I use Gelbe Seiten Scraper with the Apify API?

Yes. Start runs with the Apify REST API or an official Apify client, then retrieve records from the run's default dataset. Keep your API token in a secret or environment variable.

#### Can I use Gelbe Seiten Scraper through an MCP Server?

Yes. The Apify MCP server can expose the Actor to compatible AI clients and agents. Review the input and expected cost before allowing an autonomous workflow to run it at scale.

#### Do I need proxies?

It depends on the source and volume. Use the default configuration first. For larger or geographically sensitive jobs, select an appropriate proxy configuration only when the Actor supports it.

#### Is it legal to scrape this data?

Scraping rules vary by source, jurisdiction, data type, and intended use. Collect only data you are authorized to access, respect applicable terms and privacy laws, and avoid restricted or personal data misuse. This documentation is not legal advice.

#### Your feedback

If a field is missing, a source layout has changed, or you need a supported use case documented, open an issue on the Actor page with a reproducible input and run ID.

# 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 '<YOUR_API_TOKEN>' with your token
const client = new ApifyClient({
    token: '<YOUR_API_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 '<YOUR_API_TOKEN>' with your token.
client = ApifyClient("<YOUR_API_TOKEN>")

# 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 <YOUR_API_TOKEN>"
            ]
        }
    }
}

```

## OpenAPI specification

Download the OpenAPI definition: https://api.apify.com/v2/actors/S0eeCZEzmHP0L7i69/builds/zfFZIz5eJE21h9qJT/openapi.json