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

Agent-native, maschinenlesbare Ressource: Friseur-Verzeichnis (42,078 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/mcp.json` — MCP-Server-Card (Registry-Schema, Discovery)
- `/auth.md` — Zugriffs-/Auth-Hinweise fuer Maschinen-Clients
- `/.well-known/trust-pledge.json` / `did.json` / `jwks.json` — Trust-Artefakte
- `/mcp` — MCP-Tool `search_friseur`
- `/sitemap.xml` — XML-Sitemap
- `/agents.md` — Agent-Instruktionen (when to use)

## WebMCP (In-Page-Tools)
Die Startseite registriert im Browser des Besuchers read-only WebMCP-Tools via `document.modelContext`: `search_friseur_by_plz`, `search_friseur_by_coords`, `get_friseur_directory_info` — typisierte JSON-Schemas, readOnlyHint, gleiche Daten wie `/api/search`. Spec: https://webmachinelearning.github.io/webmcp/

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

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

Beispiel-Antwort (gekürzt):
{"meta":{"domain":"friseur-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