# Gelbe Seiten Scraper - German Business Directory (`studio-amba/gelbeseiten-scraper`) Actor

Search and extract business listings from Gelbe Seiten (gelbeseiten.de), Germany's yellow pages directory. Get business names, categories, addresses, zip codes, cities, phone numbers, websites, and ratings by keyword and location. No API key, no login required.

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

## Pricing

from $12.00 / 1,000 result scrapeds

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

## Gelbe Seiten Scraper — German Business Directory Data

Scrape business listings from [Gelbe Seiten](https://www.gelbeseiten.de), Germany's yellow pages directory with millions of registered businesses across every trade and city. Search by category keyword and location, and export clean structured business records with names, categories, addresses, zip codes, phone numbers, websites, and customer ratings. No login, no cookies, no API key.

### Why use this actor?

Gelbe Seiten is the reference directory for local businesses in Germany. Craftsmen, doctors, lawyers, tax advisors, restaurants, salons, workshops: if a German business wants to be found, it is listed here. Every listing carries the data a sales or research team actually needs: what the business does, where it sits, and how to reach it.

Typical uses:

- **Lead generation** — build prospect lists for a trade and city, ready for a CRM import.
- **Local market research** — count and map businesses per category and region, compare cities.
- **Data enrichment** — match business names to addresses, phone numbers, websites, and ratings.
- **Competitor analysis** — list every provider in a category around a location, sorted with ratings.

The actor reads the server-rendered search results directly, so records are complete and consistent. It only returns contact details that businesses publish openly on the directory.

### How to scrape Gelbe Seiten data

1. Open the actor and set a **Search Query** — a trade or category keyword in German, such as `friseur`, `steuerberater`, `zahnarzt`, or `italienisches restaurant`. Business names work too.
2. Set a **Location** — a city, town, or zip code (`berlin`, `muenchen`, `frankfurt am main`, `10115`).
3. Set **Max Results** to the number of businesses you want.
4. Keep the residential proxy prefill and click **Start**.
5. When the run finishes, export the dataset as JSON, CSV, or Excel, or pull it from the Apify API.

The actor loads the first results page and then pages through the load-more endpoint automatically until it reaches your Max Results or runs out of matching businesses.

### Input

| Field | Type | Required | Description |
|-------|------|----------|-------------|
| `searchQuery` | String | No | Trade or category keywords in German (e.g. `friseur`, `steuerberater`). Defaults to `friseur` if empty. |
| `location` | String | No | City, town, or zip code to search in (e.g. `berlin`, `10115`). Defaults to `berlin` if empty. |
| `maxResults` | Integer | No | Maximum number of businesses to return (default: 50, max: 1000). |
| `proxyConfiguration` | Object | No | Proxy settings. Residential proxies recommended. |

Example input:

```json
{
    "searchQuery": "steuerberater",
    "location": "muenchen",
    "maxResults": 100,
    "proxyConfiguration": {
        "useApifyProxy": true,
        "apifyProxyGroups": ["RESIDENTIAL"]
    }
}
````

### Output

One record per business listing:

| Field | Type | Description |
|-------|------|-------------|
| `businessName` | String | Business name as listed on Gelbe Seiten |
| `category` | String | Primary branche/category (e.g. `Friseure`, `Steuerberater`) |
| `address` | String | Street address |
| `zipCode` | String | German postal code (PLZ) |
| `city` | String | City |
| `district` | String | City district (Stadtteil), when shown |
| `phone` | String | Phone number, when publicly listed |
| `website` | String | Business's own website, when published |
| `rating` | Number | Average customer rating (0–5), when shown |
| `reviewCount` | Number | Number of customer reviews, when shown |
| `profileText` | String | Short free-text presentation from the listing |
| `openingStatus` | String | Opening state at scrape time (e.g. `Geschlossen – Öffnet um 10:00`) |
| `distance` | String | Distance from the search center (e.g. `3,4 km`) |
| `url` | String | Full URL of the business profile on Gelbe Seiten |
| `businessId` | String | Internal Gelbe Seiten listing ID |
| `searchQuery` | String | The query that returned this business |
| `searchLocation` | String | The location used for the search |
| `scrapedAt` | String | ISO timestamp of the scrape |

Example output:

```json
{
    "businessName": "Hair Affair",
    "category": "Friseure",
    "address": "Friesenstr. 8",
    "zipCode": "10965",
    "city": "Berlin",
    "district": "Kreuzberg",
    "phone": "030 6 91 90 89",
    "website": null,
    "rating": 5.0,
    "reviewCount": 1,
    "profileText": "Im Friseursalon Hair Affair in Berlin bietet Inhaberin Jessica Koch Ihnen die ganze Palette von klas...",
    "openingStatus": "Geschlossen – Öffnet um 10:00",
    "distance": "3,4 km",
    "url": "https://www.gelbeseiten.de/gsbiz/dbb0b6e7-fc4d-48ee-8309-909beb906c9c",
    "businessId": "dbb0b6e7-fc4d-48ee-8309-909beb906c9c",
    "searchQuery": "friseur",
    "searchLocation": "berlin",
    "scrapedAt": "2026-07-10T09:30:00.000Z"
}
```

### Cost estimate

The actor uses lightweight HTTP requests (no browser). The first 50 businesses come from a single page load; after that each request adds 10 businesses. A 100-result run typically finishes in under a minute and uses only a few cents of platform credits plus the per-result fee.

### Tips

- Search queries and locations are the same words you would type on gelbeseiten.de. German keywords match best (`rechtsanwalt`, not `lawyer`).
- Zip codes work as locations and give tighter geographic scoping than city names.
- Multi-word queries are fine: `italienisches restaurant`, `frankfurt am main`.
- Ratings and websites only appear when the business publishes them; expect them on a subset of records.

### Limitations

- The actor scrapes the search results list, not the full detail pages. Fields that only exist on detail pages (opening-hours tables, email addresses, photos) are not included.
- Gelbe Seiten covers Germany only.
- `distance` is relative to the search center Gelbe Seiten picks for your location.

### Legal

This actor only extracts business information that is publicly listed on the Gelbe Seiten directory, where businesses publish it precisely to be found and contacted. No login is bypassed and no private data is collected. You are responsible for using the data in compliance with applicable laws (GDPR, competition law) in your jurisdiction.

# Actor input Schema

## `searchQuery` (type: `string`):

Trade, category, or business keywords in German (e.g. 'friseur', 'steuerberater', 'zahnarzt', 'restaurant'). Business names also work.

## `location` (type: `string`):

City, town, or zip code to search in (e.g. 'berlin', 'muenchen', 'frankfurt am main', '10115').

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

Maximum number of businesses to return. The first results page carries 50 listings; further listings load in batches of 10.

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

Proxy settings. Residential proxies recommended for reliable access.

## Actor input object example

```json
{
  "searchQuery": "friseur",
  "location": "berlin",
  "maxResults": 20,
  "proxyConfiguration": {
    "useApifyProxy": true,
    "apifyProxyGroups": [
      "RESIDENTIAL"
    ]
  }
}
```

# 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": "friseur",
    "location": "berlin",
    "maxResults": 20,
    "proxyConfiguration": {
        "useApifyProxy": true,
        "apifyProxyGroups": [
            "RESIDENTIAL"
        ]
    }
};

// Run the Actor and wait for it to finish
const run = await client.actor("studio-amba/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 = {
    "searchQuery": "friseur",
    "location": "berlin",
    "maxResults": 20,
    "proxyConfiguration": {
        "useApifyProxy": True,
        "apifyProxyGroups": ["RESIDENTIAL"],
    },
}

# Run the Actor and wait for it to finish
run = client.actor("studio-amba/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 '{
  "searchQuery": "friseur",
  "location": "berlin",
  "maxResults": 20,
  "proxyConfiguration": {
    "useApifyProxy": true,
    "apifyProxyGroups": [
      "RESIDENTIAL"
    ]
  }
}' |
apify call studio-amba/gelbeseiten-scraper --silent --output-dataset

```

## MCP server setup

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

```

## OpenAPI specification

```json
{
    "openapi": "3.0.1",
    "info": {
        "title": "Gelbe Seiten Scraper - German Business Directory",
        "description": "Search and extract business listings from Gelbe Seiten (gelbeseiten.de), Germany's yellow pages directory. Get business names, categories, addresses, zip codes, cities, phone numbers, websites, and ratings by keyword and location. No API key, no login required.",
        "version": "0.1",
        "x-build-id": "qgszBK1EMP7yJbQ3r"
    },
    "servers": [
        {
            "url": "https://api.apify.com/v2"
        }
    ],
    "paths": {
        "/acts/studio-amba~gelbeseiten-scraper/run-sync-get-dataset-items": {
            "post": {
                "operationId": "run-sync-get-dataset-items-studio-amba-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/studio-amba~gelbeseiten-scraper/runs": {
            "post": {
                "operationId": "runs-sync-studio-amba-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/studio-amba~gelbeseiten-scraper/run-sync": {
            "post": {
                "operationId": "run-sync-studio-amba-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",
                "properties": {
                    "searchQuery": {
                        "title": "Search Query (Branche)",
                        "type": "string",
                        "description": "Trade, category, or business keywords in German (e.g. 'friseur', 'steuerberater', 'zahnarzt', 'restaurant'). Business names also work.",
                        "default": "friseur"
                    },
                    "location": {
                        "title": "Location (Ort)",
                        "type": "string",
                        "description": "City, town, or zip code to search in (e.g. 'berlin', 'muenchen', 'frankfurt am main', '10115').",
                        "default": "berlin"
                    },
                    "maxResults": {
                        "title": "Max Results",
                        "minimum": 1,
                        "maximum": 1000,
                        "type": "integer",
                        "description": "Maximum number of businesses to return. The first results page carries 50 listings; further listings load in batches of 10.",
                        "default": 50
                    },
                    "proxyConfiguration": {
                        "title": "Proxy Configuration",
                        "type": "object",
                        "description": "Proxy settings. Residential proxies recommended for reliable access.",
                        "default": {
                            "useApifyProxy": true,
                            "apifyProxyGroups": [
                                "RESIDENTIAL"
                            ]
                        }
                    }
                }
            },
            "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
                                    }
                                }
                            }
                        }
                    }
                }
            }
        }
    }
}
```