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

Agent-native, maschinenlesbare Ressource: Hausgeräte-Kundendienst-Verzeichnis (122 Einträge) als JSON-API, MCP-Tool und Markdown-Doku.

## API (JSON)
- `GET /api/search?plz=10115&limit=10` — nach Entfernung sortiert (empfohlen)
- `GET /api/search?lat=52.52&lon=13.40&limit=10` — nach Koordinaten
- `GET /api/search?q=&limit=10` — nach Name/Stadt
- `GET /api/booking=only&plz=10115` — nur online-buchbare Betriebe
- `GET /api/records` — alle Datensätze
- `GET /api/cities` — Ortsverteilung
- `GET /api/booking-offers` — online-buchbare Betriebe mit direkter Buchungs-URL

## Felder je Datensatz
name, city, street, housenumber, postcode, lat, lon, phone, website, email, opening_hours, completeness_score, booking_capable, booking_platform, booking_url

## Maschinenlesbare Ressourcen
- `/llms.txt` — Zusammenfassung für LLMs (Markdown)
- `/openapi.json` — OpenAPI-Schema
- `/server.json` / `/.well-known/agent-card.json` — MCP / A2A Agent Card
- `/.well-known/trust-pledge.json` / `did.json` / `jwks.json` — Trust-Artefakte
- `/mcp` — MCP-Tool `search_hausgeraetekundendienst`
- `/sitemap.xml` — XML-Sitemap
- `/agents.md` — Agent-Instruktionen (when-to-use)

## Auth
Diese öffentliche Verzeichnis-API benötigt keine Authentifizierung (read-only, öffentliche Daten). Alle Endpunkte sind ohne Key erreichbar. Solltest du später einen API-Key für höhere Limits brauchen, kontaktiere uns unter /contact.

## Beispiel-Anfrage (curl)
    curl 'https://kundendienst-in-meiner-naehe.de/api/search?plz=10115&limit=3'

Beispiel-Antwort (gekürzt):
{"meta":{"domain":"kundendienst-in-meiner-naehe.de","query":{...},"count":3},"records":[{...}]}

## Fehlerbehandlung
Fehler sind als `application/problem+json` (RFC 9457) strukturiert mit den Feldern `type`, `title`, `status`, `code`, `detail`, `instance`. Ein unbekannter API-Pfad liefert:
HTTP 404 {
  "code": "NOT_FOUND",
  "title": "Nicht gefunden",
  "status": 404
}

## Wechsel zu Versionierung
Versionierte Endpunkte unter `/v1/*` (Alias zu `/api/*`). Siehe `/openapi.json` für das vollständige Kontrakt.

## Lizenz & Quellen
OpenStreetMap (ODbL 1.0, © OpenStreetMap contributors) und Overture Maps Foundation (CDLA-Permissive-2.0). Kontaktdaten nur, wenn öffentlich verfügbar. Daten ohne Gewähr.

Impressum: /impressum · Datenschutz: /privacy · Kontakt: /contact