# Gelbe Seiten Business Scraper (`khadinakbar/gelbe-seiten-scraper`) Actor

Extract public German business listings from Gelbe Seiten by service and location, with contact details, ratings, addresses, and source URLs.

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

## Pricing

from $5.00 / 1,000 business founds

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 Business Scraper

Collect public German business listings from Gelbe Seiten by business type and city, postal code, or district. Each dataset item represents one deduplicated business and includes its name, category, address, public phone/email/website where shown, ratings, and the original Gelbe Seiten detail-page URL.

### Best fit

Use this Actor for local market research, German B2B prospecting, and directory-data workflows that start with a business type and location. It accepts either search pairs such as `Zahnarzt` + `Berlin` or existing Gelbe Seiten result and business URLs. It is not a tool for private data, login-only information, or businesses outside Gelbe Seiten.

### Quick start

```json
{
  "searches": [{ "query": "Zahnarzt", "location": "Berlin" }],
  "maxResults": 50,
  "enrichDetails": true
}
```

Set `enrichDetails` to `false` for faster result-card extraction. The actor follows Gelbe Seiten' own continuation endpoint until it reaches `maxResults` or exhausts the search.

### Input reference

| Field | Type | What it controls |
| --- | --- | --- |
| `searches` | array | One or more `{ query, location }` pairs, such as `Zahnarzt` and `Berlin`. |
| `startUrls` | array | Existing Gelbe Seiten search or business URLs; they retain the URL's public filters. |
| `maxResults` | integer | A 1–500 cap on unique business rows and the matching billable events. |
| `enrichDetails` | boolean | Whether to visit each public detail page for additional public contact and opening-hour fields. |

### Output

```json
{
  "businessName": "Zahnarztpraxis Petra Hartmann",
  "primaryCategory": "Zahnärzte",
  "address": "Friedelstr. 14, 12047 Berlin (Neukölln)",
  "phone": "030 6 24 31 33",
  "email": "info@example.de",
  "rating": 4.9,
  "detailPageUrl": "https://www.gelbeseiten.de/gsbiz/...",
  "scrapedAt": "ISO 8601 extraction timestamp"
}
```

Optional public fields are `null` when Gelbe Seiten does not display them. Every item retains `sourceUrl` and `detailPageUrl` for provenance.

### Practical workflow

A local-services agency can search `Steuerberater` in `Hamburg`, limit the run to 100 businesses, then sort the returned records by rating and retain the source URL with each CRM import. The result is a defensible territory list: a person reviewing the import can trace every contact field back to the matching public directory page.

### Use through the API

```bash
curl "https://api.apify.com/v2/acts/khadinakbar~gelbe-seiten-scraper/runs?token=$APIFY_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"searches":[{"query":"Zahnarzt","location":"Berlin"}],"maxResults":25,"enrichDetails":false}'
```

After completion, read the default dataset and the `OUTPUT` key in the default key-value store. Keep `detailPageUrl` with any downstream record so the source remains reviewable.

### AI agents through Apify MCP

> Use the Gelbe Seiten Business Scraper to collect up to 25 public dental practices in Berlin. Return business name, address, phone, website, rating, and source URL. Read the terminal outcome and dataset, preserve source URLs as provenance, and stay within the requested result cap and cost.

The AI agent can page through the dataset after the run and use `RUN_SUMMARY` to understand the final scope and any warnings.

### Pricing

This Actor uses Pay per event plus Apify platform usage. It charges `$0.005` for each unique, validated `business-found` dataset row and `$0.00005` when a run starts. A 50-business run has a maximum event charge of `$0.25`, plus platform usage. Open the live Pricing tab for the current event details and use Apify run cost controls for a hard billing limit.

### Builder's note

I designed the actor around the fact that Gelbe Seiten exposes the first 50 result cards as HTML but loads further cards through a POST continuation endpoint. The actor keeps that continuation path separate from detail enrichment and only charges after a complete record has passed validation and reached the dataset. This prevents a retry, a duplicate card, or a missing optional field from becoming a billable result.

### Focused standalone workflow

This actor works as a focused standalone workflow for public German Gelbe Seiten business records and preserves the source page for later validation.

### Responsible use

Use only public information for lawful, authorized workflows and respect applicable privacy, marketing, and data-protection requirements. Verify records against their source page before outreach or other consequential use.

# Actor input Schema

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

Business-type and location pairs to search on Gelbe Seiten. Example: \[{"query":"Zahnarzt","location":"Berlin"}]. Defaults to a Berlin dentist search. This is not a list of URLs; use Gelbe Seiten URLs for an existing results or business page.

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

Existing Gelbe Seiten search-result or business-detail URLs. Example: https://www.gelbeseiten.de/branchen/zahnarzt/berlin. Use this to preserve a search URL's filters; URLs outside gelbeseiten.de are rejected.

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

Maximum unique business records to return across every input. Example: 50. Defaults to 50 and accepts 1 through 500. This is a business-row cap, not a page count, and it also caps billable business-found events.

## `enrichDetails` (type: `boolean`):

Visit each listed business page to collect additional publicly displayed contact and opening-hour data. Example: true. Defaults to true; disable it for faster list-card-only output. This does not discover private contact information.

## Actor input object example

```json
{
  "searches": [
    {
      "query": "Zahnarzt",
      "location": "Berlin"
    }
  ],
  "startUrls": [],
  "maxResults": 50,
  "enrichDetails": true
}
```

# Actor output Schema

## `dataset` (type: `string`):

No description

## `output` (type: `string`):

No description

## `runSummary` (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": [
        {
            "query": "Zahnarzt",
            "location": "Berlin"
        }
    ],
    "startUrls": [],
    "maxResults": 50,
    "enrichDetails": true
};

// Run the Actor and wait for it to finish
const run = await client.actor("khadinakbar/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 = {
    "searches": [{
            "query": "Zahnarzt",
            "location": "Berlin",
        }],
    "startUrls": [],
    "maxResults": 50,
    "enrichDetails": True,
}

# Run the Actor and wait for it to finish
run = client.actor("khadinakbar/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 '{
  "searches": [
    {
      "query": "Zahnarzt",
      "location": "Berlin"
    }
  ],
  "startUrls": [],
  "maxResults": 50,
  "enrichDetails": true
}' |
apify call khadinakbar/gelbe-seiten-scraper --silent --output-dataset

```

## MCP server setup

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

```

## OpenAPI specification

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