# Gelbe Seiten Scraper - German B2B Business Directory (`aidnurs/gelbeseiten-scraper`) Actor

Scrape Gelbe Seiten (gelbeseiten.de) by category and city: business name, category, address, PLZ, phone, website, rating, reviews and opening hours. Reads district pages to go beyond 50 per city. Duplicates free, respects robots.txt.

- **URL**: https://apify.com/aidnurs/gelbeseiten-scraper.md
- **Developed by:** [Nursultan Imanov](https://apify.com/aidnurs) (community)
- **Categories:** Lead generation
- **Stats:** 2 total users, 1 monthly users, 100.0% runs succeeded, 0 bookmarks
- **User rating**: No ratings yet

## Pricing

from $1.50 / 1,000 businesses

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/actors/running/actors-in-store.md#pay-per-event

## What's an Apify Actor?

An Actor is a serverless cloud program that runs on the Apify platform. It has two run modes.
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.

Apify vocabulary and the platform model are defined once, in the agent quickstart at https://apify.com/agents.md.

## 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.

Do not guess an integration path. Every one of them is in the agent quickstart at https://apify.com/agents.md: the Apify MCP server, Agent Skills with the Apify CLI, the JavaScript and Python clients, the REST API, and the account-free path for an agent with no human to sign in. It also carries the rule on stating cost before the first paid run.

For examples already wired to this Actor's own input schema, see the [API](#api) section below.

Each client library has reference documentation the quickstart does not restate: [JavaScript/TypeScript](https://docs.apify.com/api/client/js/docs.md) (`npm install apify-client`) and [Python](https://docs.apify.com/api/client/python/docs.md) (`pip install apify-client`).

# README

### What does Gelbe Seiten Scraper do?

**Gelbe Seiten Scraper** extracts business listings from [Gelbe Seiten](https://www.gelbeseiten.de) (gelbeseiten.de), Germany's best-known business directory (Yellow Pages Germany). Pick one or more categories (Branchen) and cities (Orte) and get clean, structured B2B data: **business name, category, street, PLZ (postal code), city, district, business phone, website, rating and number of reviews**, and optionally **weekly opening hours, GPS coordinates, description, services and payment methods**.

Use it as a **Gelbe Seiten API** for market research, local competitor analysis, territory planning, B2B lead lists of companies (Handwerker, Steuerberater, Friseure, Ärzte, Restaurants...), or to enrich your CRM with addresses and websites.

### Why use this Gelbe Seiten scraper?

- **More than 50 per city.** A Gelbe Seiten city page shows only the first 50 businesses. The Actor also reads the city's district pages (Berlin Bezirke, Munich, Leipzig or Hamburg Stadtteile...) and merges them: about 420 unique electricians in Berlin instead of 50.
- **Clean fields.** Street, PLZ, city and district split; rating as a number; website decoded; one record per business.
- **Opening hours on request.** Turn on *Include opening hours and details* to get the weekly hours (`Mo 09:00-12:00`...), latitude/longitude, description, services and payment methods. Same price.
- **No duplicates charged.** A business listed in several districts or categories is saved and billed once.
- **Privacy by default.** E-mail addresses are off by default. When turned on, only role mailboxes (info@, kontakt@, office@...) are returned; personal-looking addresses are never returned.
- **Respectful and fast.** Plain HTTP, no browser, no login, follows robots.txt: 400+ businesses in about 20 seconds.

### How much does it cost to scrape Gelbe Seiten?

**$1.50 per 1,000 businesses** saved to the dataset. Duplicates, unknown categories and empty searches are free. Cap spending with *Max businesses* and the run's maximum cost.

### How to scrape Gelbe Seiten

1. Enter **Categories (Branchen)** as written on Gelbe Seiten: `Elektriker`, `Friseur`, `Steuerberater`, `Heizung & Sanitär`, `Zahnarzt`...
2. Enter **Cities (Orte)**: `Berlin`, `München`, `Köln`, or a district like `Berlin Bezirk Mitte`. Every category is combined with every city.
3. Or paste **Gelbe Seiten URLs**: listing pages like `https://www.gelbeseiten.de/branchen/elektriker/berlin` or single business pages `https://www.gelbeseiten.de/gsbiz/<id>`.
4. Set **Max businesses**, and turn on details or e-mails if you need them.
5. Click **Start** and download JSON, CSV or Excel, or use the Apify API.

Not sure about the category name? Open the [Gelbe Seiten Branchenbuch](https://www.gelbeseiten.de/branchenbuch) and use the name from there. If a category/city pair does not exist on Gelbe Seiten, the Actor logs it and moves on at no cost.

### Input example

```json
{
  "branchen": ["Elektriker", "Heizung & Sanitär"],
  "orte": ["Berlin", "Potsdam"],
  "maxItems": 1000,
  "includeDistricts": true,
  "includeDetails": true,
  "includeEmails": false
}
```

### Output example

```json
{
  "id": "c8d1de24-3efc-4429-a0d3-eff63484a56e",
  "listingId": "1095012971",
  "name": "Blachnierz & Söhne Elektroinstallationsges. mbH",
  "category": "Elektroinstallationen",
  "street": "Buckower Chaussee 82",
  "postalCode": "12277",
  "city": "Berlin",
  "district": "Marienfelde",
  "phone": "030 7 21 50 20",
  "website": "https://www.elektro-bs.de",
  "rating": null,
  "reviewsCount": 0,
  "isHighlighted": false,
  "url": "https://www.gelbeseiten.de/gsbiz/c8d1de24-3efc-4429-a0d3-eff63484a56e",
  "country": "DE",
  "latitude": 52.410816,
  "longitude": 13.374427,
  "openingHours": ["Mo 09:00-12:00", "Mo 14:00-17:30", "Di 09:00-12:00", "Di 14:00-17:30", "Fr 09:00-12:00", "Fr 14:00-17:30"],
  "services": ["Störungsbeseitigungen", "Projektierung", "Alarmanlageninstallation"],
  "paymentMethods": "Bar, Rechnung, Vorkasse, electronic cash",
  "lastUpdated": "2026-08-30",
  "detailsScraped": true,
  "email": null,
  "source": "gelbeseiten.de",
  "searchUrl": "https://www.gelbeseiten.de/branchen/elektriker/berlin",
  "scrapedAt": "2026-10-12T21:10:00+00:00"
}
```

### Fields you get

| Field | Description |
|---|---|
| `name`, `category` | Business name and main category on Gelbe Seiten |
| `street`, `postalCode`, `city`, `district`, `country` | Address split into parts (PLZ = postal code) |
| `phone` | Business phone number as published in the directory |
| `website` | Business website |
| `rating`, `reviewsCount` | Average rating (1-5) and number of reviews on Gelbe Seiten |
| `isHighlighted` | Premium/partner listing on Gelbe Seiten |
| `logoUrl`, `shortDescription` | Logo and teaser text when present |
| `openingHours` | Weekly opening hours (with details on) |
| `latitude`, `longitude` | GPS coordinates (with details on) |
| `description`, `services`, `paymentMethods`, `lastUpdated`, `businessTypes` | From the business page (with details on) |
| `email` | Role mailbox only, when *Include business e-mail* is on |
| `id`, `listingId`, `url`, `source`, `searchUrl`, `scrapedAt` | Identifiers and run metadata |

### Limits

- Gelbe Seiten's robots.txt closes its search (`/suche`), and the "Mehr anzeigen" button loads more results through that search, so this Actor reads the first 50 businesses of each listing page plus the district pages. Very large categories in a single district can therefore be incomplete. To cover more, add neighbouring towns or more specific categories.
- Ratings, websites, opening hours and logos are only present when the business published them (for example, about 1 in 10 electricians in Berlin has reviews).

### FAQ

**Is it legal to scrape Gelbe Seiten?** The Actor reads only public pages, without login, and respects robots.txt. The data is business listing data. **B2B use only:** you are responsible for complying with GDPR and the German UWG. Phone numbers and e-mails of sole proprietors can be personal data. Do not use the results for unsolicited e-mail or phone marketing (cold e-mail spam).

**Why are e-mails off by default?** Many small businesses list private addresses. When you turn e-mails on, only generic role mailboxes are returned, and e-mails inside descriptions are masked unless e-mails are on.

**Do I need a proxy?** Usually not. If Gelbe Seiten starts blocking, the Actor switches to Apify Proxy when it is enabled in the input.

**Something broke or a field is missing?** Open an issue on the Actor page with your input and run ID. We usually reply within a day.

# Actor input Schema

## `branchen` (type: `array`):

Business categories as written on Gelbe Seiten, one per line ("Elektriker", "Friseur", "Steuerberater", "Heizung & Sanitär"). Every category is combined with every city below.

## `orte` (type: `array`):

German cities or towns, one per line ("Berlin", "München", "Köln"). A district works too: "Berlin Bezirk Mitte", "München Stadtteil Schwabing".

## `startUrls` (type: `array`):

Optional. Listing URLs like https://www.gelbeseiten.de/branchen/elektriker/berlin or single business pages like https://www.gelbeseiten.de/gsbiz/<id>. Search pages (/suche) are closed by robots.txt and skipped.

## `maxItems` (type: `integer`):

Maximum number of businesses to save in this run. You only pay for unique businesses saved to the dataset.

## `includeDistricts` (type: `boolean`):

A Gelbe Seiten city page shows at most 50 businesses. For big cities the Actor also reads the district pages the city page links to (Berlin Bezirke, Munich Stadtteile...) to get many more. Duplicates are removed and free.

## `includeDetails` (type: `boolean`):

Open every business page to add weekly opening hours, GPS coordinates, full description, services, payment methods and last update date. Slower (one extra page per business), same price.

## `includeEmails` (type: `boolean`):

Add the business e-mail when it is a role mailbox (info@, kontakt@, office@...). Personal-looking addresses (first.last@, private mail providers) are never returned. B2B use only: comply with GDPR and UWG, no unsolicited e-mail marketing.

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

Usually not needed. If Gelbe Seiten blocks the run, the Actor switches to Apify Proxy when it is enabled here.

## Actor input object example

```json
{
  "branchen": [
    "Friseur"
  ],
  "orte": [
    "Leipzig"
  ],
  "maxItems": 20,
  "includeDistricts": true,
  "includeDetails": false,
  "includeEmails": false,
  "proxyConfiguration": {
    "useApifyProxy": true
  }
}
```

# Actor output Schema

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

Scraped businesses (table view).

## `businessesFull` (type: `string`):

All fields including opening hours and details.

# 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 = {
    "branchen": [
        "Friseur"
    ],
    "orte": [
        "Leipzig"
    ],
    "maxItems": 20
};

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

# Prepare the Actor input
run_input = {
    "branchen": ["Friseur"],
    "orte": ["Leipzig"],
    "maxItems": 20,
}

# Run the Actor and wait for it to finish
run = client.actor("aidnurs/gelbeseiten-scraper").call(run_input=run_input)

# Fetch and print Actor results from the run's dataset (if there are any)
print(f"💾 Check your data here: https://console.apify.com/storage/datasets/{run.default_dataset_id}")
for item in client.dataset(run.default_dataset_id).iterate_items():
    print(item)

# 📚 Want to learn more 📖? Go to → https://docs.apify.com/api/client/python/docs/quick-start

```

## CLI example

```bash
echo '{
  "branchen": [
    "Friseur"
  ],
  "orte": [
    "Leipzig"
  ],
  "maxItems": 20
}' |
apify call aidnurs/gelbeseiten-scraper --silent --output-dataset

```

## MCP server setup

```json
{
    "mcpServers": {
        "apify": {
            "type": "http",
            "url": "https://mcp.apify.com/?tools=fetch-actor-details,aidnurs/gelbeseiten-scraper"
        }
    }
}
```

The hosted server signs you in with OAuth on first connect, so no API token belongs in this config. Clients without OAuth support can send an `Authorization: Bearer <APIFY_API_TOKEN>` header instead, using a token from API & Integrations in Apify Console (https://console.apify.com/settings/integrations).

## OpenAPI specification

Download the OpenAPI definition: https://api.apify.com/v2/actors/RvXNJweq99cPnNnpx/builds/4CvCKLWVfVZ3FfMd8/openapi.json