# werbeagentur-in-meiner-naehe.de — Entwicklerhandbuch

Agent-native Ergänzung zum deutschen Agenturverzeichnis. Aktuelle Bestandszahlen
stehen auf der Startseite. Menschliche Website unter
https://www.werbeagentur-in-meiner-naehe.de — dieses Dokument beschreibt die
zusätzliche JSON-API und das MCP-Tool für Entwickler und KI-Agenten.

## API (JSON)

- `GET /api/search?plz=40213&limit=10` — Umkreissuche (100 km) nach PLZ, nach Entfernung sortiert
- `GET /api/search?lat=51.23&lng=6.77&limit=10` — Umkreissuche nach Koordinaten
- `GET /api/search?plz=40213&keyword=SEO%20Agentur` — nach Leistungsbereich gefiltert
- `GET /api/search?plz=40213&q=studio` — zusätzliche Namens-/Stadt-Suche

Dieselbe Logik (Radius, Deduplizierung nach Domain, Sortierung) wie die
menschliche Umkreissuche unter `/suche?plz=...`.

## Felder je Ergebnis

`name`, `url`, `domain`, `email`, `phone`, `city`, `cityName`, `keyword`,
`listedCityCount`, `distance_km`

`distance_basis: "listed_city_centroid"` kennzeichnet die ungefähre Distanz zum
Mittelpunkt der gelisteten Stadt, nicht zur Anbieteradresse. Bei geprüften
Websites ergänzen `source_evidence` (Belege mit Quelle, Abrufdatum, Hash) und
`website_address_city` die vorhandenen Felder. Die Adressstadt kann von
`cityName` abweichen. Sie ist eine Angabe des Anbieters und kein Vor-Ort-Audit.
`snippet` fasst dann die belegten Leistungsangaben statt älterer Werbetexte
zusammen. Die Originaldaten werden nicht überschrieben.

## Leistungsbereiche (keyword-Filter)

SEO Agentur, Werbeagentur, Digitalagentur, Social Media Agentur, Marketing Agentur,
Webdesign Agentur, Kreativagentur, Branding Agentur, Online Marketing Agentur,
PR Agentur, Performance Marketing Agentur, Content Marketing Agentur

## Maschinenlesbare Ressourcen

- `/llms.txt` — Zusammenfassung für LLMs
- `/openapi.json` — OpenAPI-Schema
- `/agents.md` — Agent-Instruktionen (when-to-use)
- `/mcp` — MCP-Tool `search_werbeagenturen`
- `/sitemap.xml`, `/locations.geojson`, `/locations.kml`

## Auth

Öffentliche, kostenlose Read-Only-API. Kein API-Key nötig.

## Beispiel

```
curl 'https://www.werbeagentur-in-meiner-naehe.de/api/search?plz=40213&limit=3'
```

## Einordnung

Das Verzeichnis ist keine Rangliste, Empfehlung oder Zertifizierung. Details siehe
`/llms.txt`.

## Website-Belege

`GET /api/topics` liefert belegte Leistungen, Preis- und Buchungserwähnungen sowie Adressangaben (`kind: location`) mit Quellen-URL, Abrufdatum und Inhaltshash. `entries` ist auf gelistete Domains begrenzt; `topics` enthält lokale Gruppen erst ab fünf unterschiedlichen Domains mit passender Stadt. Manuell geprüfte Gruppen benötigen zusätzlich einen aktuellen Adressbeleg. Eine Website-Angabe gilt nicht automatisch für jeden Standort. Die vorhandene Suche und deren Kategorien bleiben unverändert. Frische manuell geprüfte Belege ergänzen den Live-Feed und bleiben bei Feed-Ausfall verfügbar. `update_status` kennzeichnet den Feed-Zustand. Belege verfallen nach 90 Tagen; ein erneuter Abruf allein verlängert keine manuelle Prüfung.