# Gelbe Seiten Scraper (`plowdata/gelbe-seiten`)

Gather leads and information from one of Germany's most comprehensive business directories, Gelbe Seiten.
Download your data as HTML table, JSON, CSV, XML, Excel, RSS, or JSONL.

- **URL**: https://beta-securitybyobscurity.apify.com/plowdata/gelbe-seiten.md
- **Developed by:** [Frederic](https://beta-securitybyobscurity.apify.com/plowdata) (community)
- **Categories:** Lead generation, Automation
- **Stats:** 196 total users, 16 monthly users, 100.0% runs succeeded, 13 bookmarks
- **User rating**: 4.95 out of 5 stars

## Pricing

$10.00/month + usage

To use this Actor, you pay a monthly rental fee to the developer. The rent is subtracted from your prepaid usage every month after the free trial period.
You also pay for the Apify platform usage, which gets cheaper the higher Apify subscription plan you have.

Learn more: https://docs.apify.com/platform/actors/running/actors-in-store#rental-actors

# README

## Gelbe Seiten Scraper

This scraper is a specialized information gathering / lead-gen tool for the German market.\
It's designed to extract all information from Gelbe Seiten listings, including **emails**, **phone numbers**, **addresses**, **reviews**, booking.com information and more.\
Make use of one of the most comprehensive business directories in Germany, and gather all the information you need in one go.

### Why choose this scraper?

- **Easy to use**: Just enter your search query and let the scraper do the rest.
- **No page limit**: This scraper can handle any number of pages, and will automatically stop when it reaches the end of the results.
- **Deep Extraction**: This scraper can extract all information from a listing, including reviews, photos, and more.
- **Wide Range of output formats**: Export your data as CSV, Excel, JSON, XML, or more.
- **Committed to quality**: We're constantly improving our scrapers to ensure you get the best data possible.
- **Technical support and continous improvements**: We're always here to help you with any issues you might have, and we're constantly improving our scrapers to ensure you get the best data possible. If the scraper encounters and information it cannot yet handle, it will give you a warning, but continue to scrape the rest of the data, just open an issue with the log-output and we'll get to work on it.
- **Fast**: Our scrapers are designed to be fast, so you can get the data you need quickly and easily. Even with detailed per-listing extraction, the scraper only takes ~45s to scrape 1500 listings, thats over **30 listings per second**!
- **Reliable**: The scraper is resistant to malformed data and can automatically recover from most errors. Even when starting and stopping the scraper (or if apify migrates the scraper to a different server), the scraper will continue where it left off. And thanks to it's built-in deduplication engine, it will not scrape the same listing twice, reducing any post-processing work you might have to do.
- **Strong typing**: We provide a strong typing system for the output, so you can be sure that the data you get is clean and consistent.

### Input

The scraper only has a single required input, the `query` parameter. This is the search query you would enter on the Gelbe Seiten website,
the other inputs are:

- **location**: (optional) The location to search in, if not provided, the scraper will search in all of Germany.
- **sort**: (optional) The sort-order of the results, can be either `relevance` or `bewertung`, if not provided, the scraper will fall back to Gelbe Seiten's default sort-order, `relevance`.
- **maxPages**: (optional) The maximum number of pages to scrape, if not provided, the scraper will scrape all pages. (Note that there's on average ~10 listings per page, where the last can have less)

### Output format

The scraper returns a dataset, with one item per listing, which are structured as follows:

```typescript

    // Hotels, etc. have a lot of additional information, that's provided via the embedded booking.com widget
    // This part of the output is a parsed and cleaned version of this widget 
    const BookingComInfoSchema = z.object({
        images: z.array(z.string()),
        score: z.number(),
        description: z.string(),
        outdoorArea: z.array(z.string()).optional(),
        distancing: z.array(z.string()).optional(),
        foodAndDrink: z.array(z.string()).optional(),
        safety: z.array(z.string()).optional(),
        cleaningAndDisinfection: z.array(z.string()).optional(),
        services: z.array(z.string()).optional(),
        internet: z.array(z.string()).optional(),
        general: z.array(z.string()).optional(),
        parking: z.array(z.string()).optional(),
        rooms: z.array(z.string()).optional(),
        paymentMethods: z.array(z.string()).optional(),
        openingHours: z.array(z.string()).optional(),
        receptionService: z.array(z.string()).optional(),
        foodSafety: z.array(z.string()).optional(),
        safetyFacilities: z.array(z.string()).optional(),
        poolAndWellness: z.array(z.string()).optional(),
        access: z.array(z.string()).optional(),
        activities: z.array(z.string()).optional(),
        publicTransport: z.array(z.string()).optional(),
        entertainmentAndFamilyOffers: z.array(z.string()).optional(),
        membershipAndServiceLanguages: z.array(z.string()).optional(),
        kitchen: z.array(z.string()).optional(),
        businessFacilities: z.array(z.string()).optional(),
        cleaningServices: z.array(z.string()).optional(),
        generalFacilities: z.array(z.string()).optional(),
        miscellaneous: z.array(z.string()).optional(),
        shops: z.array(z.string()).optional(),
        ski: z.array(z.string()).optional(),
    });

    // This part of the output is directly taken from gelbeseiten.de, and just passed through
    const ReviewSchema = z.object({
        text: z.string(),
        erstellungsDatumIso: z.string(),
        erstellungsDatumFormatiert: z.string(),
        bearbeitungsDatum: z.string().nullable(),
        bewertungBeiAnbieter: z.number().nullable(),
        geraetetypBewertungsabgabe: z.string().nullable(),
        bewertungsbogenTextUrl: z.string().nullable(),
        bewertungsKriteriumListe: z.array(
            z.object({
                kriterium: z.string(),
                bewertung: z.number(),
                text: z.string().nullable(),
            }),
        ).nullable(),
        bewertungsId: z.string().nullable(),
        bewertungsportal: z.string().nullable(),
        likeListe: z.array(z.object({
            benutzer: z.object({
                name: z.string().nullable(),
                nutzerprofilUrl: z.string().nullable(),
                nutzerbildUrl: z.string().nullable(),
            }),
        })).nullable(),
        partnerBewertungstextUrl: z.string().nullable(),
        bewertungNormiert: z.number().min(0).max(5),
        anzahlLikes: z.string().nullable(),
        anzahlKommentare: z.number(),
        reaktionListe: z.array(
            z.object({
                text: z.string(),
                erstellungsDatumFormatiert: z.string(),
                reaktionsTyp: z.string(),
                anzahlLikes: z.string().nullable(),
                erstellungsDatum: z.string(),
                benutzer: z.object({
                    name: z.string().nullable(),
                    nutzerprofilUrl: z.string().nullable(),
                    nutzerbildUrl: z.string().nullable(),
                }),
                spamUrl: z.string().nullable(),
            }),
        ),
        verifikationListe: z.array(z.string()),
        bewertungTextAnzahl: z.number(),
        erstellungsDatum: z.string(),
        bewertungsbogenSterneUrl: z.string().nullable(),
        produkt: z.object({
            partnerName: z.string().nullable(),
            name: z.string().nullable(),
            information: z.string().nullable(),
        }),
        benutzer: z.object({
            name: z.string().nullable(),
            nutzerprofilUrl: z.string().nullable(),
            nutzerbildUrl: z.string().nullable(),
        }),
        titel: z.string().nullable(),
        partnerName: z.string().nullable(),
        spamUrl: z.string().nullable(),
    })
    const ExtraInfoSchema = z.object({
        brands: z.array(z.string()).optional(),
        memberships: z.array(z.string()).optional(),
        languages: z.array(z.string()).optional(),
        accessibility: z.array(z.string()).optional(),
    });

    const OutputSchema = z.object({
        // Search-results
        id: z.string(),
        memberId: z.string().optional(),
        name: z.string(),
        logoURL: z.string().optional(),
        bestIndustry: z.string(),
        googleMapsAddress: z.string().optional(),
        address: z.string(),
        phone: z.string(),
        website: z.string().optional(),
        shortDescription: z.string().optional(),
        highlightLevel: z.number().optional(),
        partnerLevel: z.string().optional(),
        rating: z.number().optional(),
        ratingCount: z.number().optional(),

        // Detail-page
        email: z.string().optional(),
        openingHours: z.array(z.object({
            day: z.string(),
            hours: z.array(
                z.object({
                    closed: z.boolean(),
                    from: z.string().optional(),
                    to: z.string().optional(),
                }),
            ),
        })).optional(),
        additionalPhoneNumbers: z.array(z.object({
            title: z.string(),
            number: z.string(),
        })).optional(),
        menu: z.string().optional(),
        // TODO:
        reviews: z.array(ReviewSchema).optional(),
        description: z.string().optional(),
        acceptedPaymentMethods: z.array(z.string()).optional(),
        images: z.array(z.object({
            src: z.string(),
            caption: z.string(),
        })).optional(),
        socialAccounts: z.array(z.object({
            url: z.string(),
            type: z.enum([
                'unknown', 'facebook', 'twitter', 'instagram',
                'linkedin', 'youtube', 'google', 'google_maps', 'pinterest',
                'tiktok', 'snapchat', 'whatsapp', 'telegram',
                'xing', 'unknown',
            ]),
        })).optional(),
        brochure: z.string().optional(),
        openPositions: z.array(z.record(z.string())).optional(),
        faq: z.array(z.object({
            question: z.string(),
            answer: z.string(),
        })).optional(),
        industries: z.array(z.string()).optional(),
        services: z.array(z.string()).optional(),
        extraInfo: ExtraInfoSchema.optional(),
        bookingInfo: BookingComInfoSchema.optional(),
        // The ids of any other listings, that are related to this one
        relatedIds: z.array(z.string()).optional(),
    });
```

Note that the schema *is* enforced, so you can be sure that the data you get is clean and consistent.\
If there's any changes to the data, e.g. if additional properties are added, the schema would be updated accordingly, and you'll be notified of the changes.

### Target Audience

This scraper is designed for anyone who needs to gather information from Gelbe Seiten listings, including:

- **Marketing/Sales teams**: Use the scraper to gather leads for your sales team or to find potential customers for your marketing campaigns.
- **Business owners**: Use the scraper to gather information about your competitors or to find potential partners.
- **Researchers**: Use the scraper to gather data for your research projects or to find information for your academic papers.
- **Journalists**: Use the scraper to gather information for your articles or to find potential sources for your stories.
- **Data analysts**: Use the scraper to gather data for your analysis projects or to find information for your reports.
- **Anyone else who needs to gather information from Gelbe Seiten listings**: Use the scraper to gather information for any other purpose you might have.

# Actor input Schema

## `query` (type: `string`):

Search query (Was) for the GelbeSeiten search.

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

Location (Wo) for the GelbeSeiten search, optional.

## `sort` (type: `string`):

Sort option for the GelbeSeiten search, optional, defaults to <relevanz>.

## `maxPages` (type: `integer`):

Maximum number of pages to scrape, optional, by default all pages are scraped.

## Actor input object example

```json
{
  "query": "Cafe",
  "location": "Berlin",
  "maxPages": 1
}
```

# 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 = {
    "query": "Cafe",
    "location": "Berlin",
    "maxPages": 1
};

// Run the Actor and wait for it to finish
const run = await client.actor("plowdata/gelbe-seiten").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 = {
    "query": "Cafe",
    "location": "Berlin",
    "maxPages": 1,
}

# Run the Actor and wait for it to finish
run = client.actor("plowdata/gelbe-seiten").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 '{
  "query": "Cafe",
  "location": "Berlin",
  "maxPages": 1
}' |
apify call plowdata/gelbe-seiten --silent --output-dataset

```

## MCP server setup

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

```

## OpenAPI specification

```json
{
    "openapi": "3.0.1",
    "info": {
        "title": "Gelbe Seiten Scraper",
        "description": "Gather leads and information from one of Germany's most comprehensive business directories, Gelbe Seiten.\nDownload your data as HTML table, JSON, CSV, XML, Excel, RSS, or JSONL.",
        "version": "1.0",
        "x-build-id": "xgV8bDNLSqvh4HZb4"
    },
    "servers": [
        {
            "url": "https://api.apify.com/v2"
        }
    ],
    "paths": {
        "/acts/plowdata~gelbe-seiten/run-sync-get-dataset-items": {
            "post": {
                "operationId": "run-sync-get-dataset-items-plowdata-gelbe-seiten",
                "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/plowdata~gelbe-seiten/runs": {
            "post": {
                "operationId": "runs-sync-plowdata-gelbe-seiten",
                "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/plowdata~gelbe-seiten/run-sync": {
            "post": {
                "operationId": "run-sync-plowdata-gelbe-seiten",
                "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",
                "required": [
                    "query"
                ],
                "properties": {
                    "query": {
                        "title": "Query",
                        "type": "string",
                        "description": "Search query (Was) for the GelbeSeiten search."
                    },
                    "location": {
                        "title": "Location",
                        "type": "string",
                        "description": "Location (Wo) for the GelbeSeiten search, optional."
                    },
                    "sort": {
                        "title": "Sort",
                        "enum": [
                            "relevanz",
                            "bewertung"
                        ],
                        "type": "string",
                        "description": "Sort option for the GelbeSeiten search, optional, defaults to <relevanz>."
                    },
                    "maxPages": {
                        "title": "Max Pages",
                        "minimum": 1,
                        "type": "integer",
                        "description": "Maximum number of pages to scrape, optional, by default all pages are scraped."
                    }
                }
            },
            "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
                                    }
                                }
                            }
                        }
                    }
                }
            }
        }
    }
}
```
