Gelbe Seiten APIgelbeseiten.de ↗
Search gelbeseiten.de by keyword and location. Get business contact info, opening hours, categories, and reviews via 2 structured endpoints.
What is the Gelbe Seiten API?
The Gelbe Seiten API provides access to Germany's Yellow Pages directory through 2 endpoints, returning business listings with contact details, opening hours, customer reviews, and category data. Use search_businesses to query by keyword and location across the full gelbeseiten.de index, then pass the returned uuid to get_business_detail for a complete business record including email, website, and structured opening hours.
curl -X GET 'https://api.parse.bot/scraper/8db9e6fb-e973-409d-adcf-6c5e10667165/search_businesses?page=1&what=steuerberater&where=hamburg' \ -H 'X-API-Key: $PARSE_API_KEY'
Typed, relational, agent-ready
A generated client with real types, enums, and the links between objects — the structure a flat JSON response can't carry. Autocompletes in your editor and reads cleanly to coding agents.
- Fully typed · autocompletes
- Objects link to objects
- Typed errors & pagination
Typed Python client. Set up the SDK in your uv project, then pull this API’s typed client:
uv add parse-sdk uv run parse init uv run parse add --marketplace gelbeseiten-de-api
uv run parse add --marketplace pulls a pinned snapshot of this canonical API — it won’t change underneath you. To customize it, subscribe and swap to your own copy.
"""Gelbe Seiten API — search German businesses and retrieve full details."""
from parse_apis.gelbe_seiten_api import GelbeSeiten, BusinessNotFound
client = GelbeSeiten()
# Search for tax consultants in Hamburg — limit caps total items fetched.
for biz in client.businesses.search(what="steuerberater", where="hamburg", limit=5):
print(biz.name, biz.address, biz.phone)
# Drill down: take the first result and get full details.
first = client.businesses.search(what="restaurant", where="berlin", limit=1).first()
if first:
detail = first.details()
print(detail.name, detail.email, detail.website)
for oh in detail.opening_hours:
print(oh.day, oh.hours)
for cat in detail.categories:
print(cat)
# Typed error handling: catch BusinessNotFound for an invalid uuid.
try:
client.businesses.get(uuid="nonexistent-uuid-12345")
except BusinessNotFound as exc:
print(f"Business not found: {exc.uuid}")
print("exercised: businesses.search / business.details / businesses.get / BusinessNotFound")
Full-text search over the Gelbe Seiten business directory by keyword and location. Returns paginated results with basic contact info per listing. Page 1 returns up to 50 results; subsequent pages return 10. Each item includes a uuid usable with get_business_detail for full information.
| Param | Type | Description |
|---|---|---|
| page | integer | The page number to retrieve. |
| whatrequired | string | The keyword or category to search for (e.g., 'steuerberater', 'autohaus', 'restaurant'). |
| whererequired | string | The location to search in (e.g., 'hamburg', 'berlin', 'münchen'). |
{
"type": "object",
"fields": {
"page": "integer, current page number",
"items": "array of business listing objects with uuid, name, address, phone, and url",
"total_count": "integer, total number of results found"
},
"sample": {
"data": {
"page": 1,
"items": [
{
"url": "https://www.gelbeseiten.de/gsbiz/27d74d63-ae41-470c-8e1d-61a894e38510",
"name": "Dipl.-Kauffr. Diana Habelt, Steuerberaterin",
"uuid": "27d74d63-ae41-470c-8e1d-61a894e38510",
"phone": "040 67 04 90 40",
"address": "Am Stadtrand 56, 22047 Hamburg (Tonndorf)"
}
],
"total_count": 932
},
"status": "success"
}
}About the Gelbe Seiten API
Searching the Directory
The search_businesses endpoint accepts two required parameters: what (a keyword or category such as steuerberater or restaurant) and where (a German city or region such as hamburg or münchen). Results are paginated — page 1 returns up to 50 listings, subsequent pages return 10 each. The total_count field in the response tells you the full result set size. Each item in the items array includes a uuid, name, address, phone, and a url back to the gelbeseiten.de listing. The uuid is the key you need for the detail endpoint.
Business Detail Records
Passing a uuid to get_business_detail returns the complete record for a single business. Beyond the basic contact fields (name, phone, address), the response includes email and website when the business has published them (both return an empty string when absent), an opening_hours array with per-day day and hours objects, a categories array of classification strings, and a reviews array where each review carries author, text, and rating.
Coverage and Scope
gelbeseiten.de covers businesses registered in Germany and is one of the primary German-language local business directories. The directory spans all major sectors — professional services, automotive, food, healthcare, retail, and more — with listings that include both sole traders and larger companies. Results are tied to German city and region names as understood by the directory's own location resolver.
The Gelbe Seiten API is a managed, monitored endpoint for gelbeseiten.de — not a raw scraper you maintain. Every endpoint is automatically health-checked on a schedule, and when gelbeseiten.de changes and a check fails, the API is automatically queued for repair and re-verified. It is built to keep working as the site underneath it changes.
This isn't an official gelbeseiten.de API — it's an independent, maintained REST wrapper over public data. Where the source has no official API (or only a limited one), Parse gives you a stable contract over a source that never promised one, and keeps it current. Need a new endpoint or field? You can revise it yourself in plain English and the agent rebuilds it against the live site in minutes — contributing the change back to the shared API is free.
Will this API break when the source site changes?+
Is this an official API from the source site?+
Can I fix or extend this API myself if I need a new endpoint or field?+
What happens if I call an endpoint that has an issue?+
- Build a lead-generation tool that queries
search_businessesby trade category and city, then enriches each result viaget_business_detailto collect emails and websites. - Aggregate opening hours for a specific business type (e.g., pharmacies or locksmiths) across multiple German cities.
- Monitor customer reviews for a set of businesses by polling
reviewsfromget_business_detailon a schedule. - Compile a local competitor map for a given keyword and city using
name,address, andcategoriesfields. - Validate or enrich an existing German business database by cross-referencing phone numbers and addresses from the directory.
- Power a location-aware German business finder that surfaces contact details and hours for end users.
| Tier | Price | Credits/month | Rate limit |
|---|---|---|---|
| Free | $0/mo | 100 | 5 req/min |
| Hobby | $30/mo | 1,000 | 20 req/min |
| Developer | $100/mo | 5,000 | 100 req/min |
One credit = one API call regardless of which marketplace API you call. Exceeding the rate limit returns a 429 response. Authenticate with the X-API-Key header.
Does gelbeseiten.de offer an official developer API?+
What does `get_business_detail` return that `search_businesses` does not?+
search_businesses returns basic fields only: uuid, name, address, phone, and url. get_business_detail adds email, website, categories, opening_hours (structured per-day objects), and reviews with author, text, and rating per entry. Fetching full detail requires a separate call per business using the uuid from the search results.Is there a quirk to the pagination in `search_businesses`?+
Can I filter search results by business category or radius rather than just keyword and city?+
search_businesses endpoint accepts only what (keyword or category name as a string) and where (location string), with no radius, bounding-box, or structured category filter parameters. You can fork this API on Parse and revise it to add a filtering endpoint if your use case requires more granular geographic or category control.Does the API cover businesses outside Germany?+
where parameter resolves against German cities and regions. Searches for locations outside Germany will return no results. You can fork this API on Parse and revise it to point at a different regional Yellow Pages source if you need non-German coverage.