Such-API

Die Schnittstelle ist öffentlich und lesend, ohne Schlüssel. Durchsucht werden nur Websites, deren Besitzer sie bei GemeinsamKI Suche angemeldet und bestätigt haben. Solange der Index leer ist, antwortet /api/v1/search mit 503 index_not_ready.

GET /api/v1/search

Parameter	Bedeutung
`q`	Suchanfrage, höchstens 400 Zeichen (Pflicht). Alle Wörter müssen vorkommen, das letzte auch als Wortanfang; Umlaute und Akzente sind egal. `site:example.de` in der Anfrage begrenzt auf eine Website.
`page`	Ergebnisseite 1–10 zu je 10 Treffern (Standard 1)
`site`	wie `site:` in der Anfrage
`exact`	`1` = keine Vertipper-Korrektur: Findet die Anfrage nichts und ein Wort ist dem Index unbekannt, sucht der Dienst sonst mit dem ähnlichsten bekannten Wort (z. B. „dfiotko“ → „dfitko“) und nennt die korrigierte Anfrage in `altered_query`.

Antwort 200:

{
  "query": "bäckerei weiden", "altered_query": "", "page": 1, "market": "de-de", "site": "",
  "total": 14,
  "results": [
    {
      "title": "…", "url": "https://…", "snippet": "…", "date": "2026-10-18",
      "summary": "…", "summary_kind": "auszug | ki", "extra_snippets": ["…"],
      "verified": { "verifytrust": { "id": "6f82492c-…", "name": "…", "score": "10.0", "profile": "https://verifytrust.ai/verify/…" } },
      "images": { "logo": "https://search.gemeinsamki.de/b/b-….png", "header": "https://search.gemeinsamki.de/b/b-….jpg" }
    }
  ],
  "index": { "state": "live", "documents": 22 }
}

altered_query ist leer, wenn die Anfrage unverändert gesucht wurde; sonst die korrigierte Anfrage, zu der die Treffer gehören. verified ist null, wenn es zur Website kein verifiziertes VerifyTrust-Profil gibt. images fehlt, solange die Besitzer kein Logo oder Headerbild hinterlegt haben oder es noch nicht freigegeben ist; Logo als PNG (bis 512 Pixel), Headerbild als JPEG (bis 1600 Pixel breit, gedacht für einen Ausschnitt 3 : 1). Die Bilder dürfen nur zusammen mit dem Treffer der jeweiligen Website gezeigt werden; sie können jederzeit wegfallen (Zwischenspeicher höchstens eine Stunde). Rangfolge: Treffer im Titel vor Beschreibung, Überschriften, Zusammenfassung und Text (BM25); verifizierte Unternehmen und Startseiten leicht bevorzugt.

Fehler: 400 missing_query, 400 query_too_long, 429 rate_limited (Schutzgrenze je IP), 503 index_not_ready.

GET /api/v1/products

Produktangebote aus den freigegebenen Feeds der Händler (Format). Parameter wie oben: q (Pflicht), page (1–10 zu je 24 Angeboten), site, words=1; dazu sort=price für Preis inklusive Versand aufsteigend.

{
  "query": "espresso", "page": 1, "total": 3,
  "results": [
    {
      "id": 812, "title": "Espresso Bohnen Bio, 1 kg", "url": "https://search.gemeinsamki.de/pk/812", "shop_url": "https://www.mustershop.de/p/…",
      "image": "https://search.gemeinsamki.de/pb/….jpg", "currency": "EUR", "price": 18.9, "shipping": 4.95, "total": 23.85,
      "vat_included": true, "small_business": false, "availability": "lieferbar", "condition": "neu",
      "price_as_of": "2026-10-22T12:05:00Z",
      "unit_price": { "price": 18.9, "unit": "1 kg" }, "energy_label": null, "mandatory_notice": null,
      "merchant": { "name": "Muster Handels GmbH", "address": "Musterstraße 1, 12345 Musterstadt", "imprint": "https://…", "shop_name": "Mustershop", "host": "mustershop.de" },
      "verified": null
    }
  ],
  "display_rules": "…", "ranking": "https://search.gemeinsamki.de/ranking#produkte"
}

Wer Angebote anzeigt, zeigt je Angebot zusammen: Gesamtpreis mit Hinweis „inkl. MwSt.“ (bzw. Kleinunternehmer), Versandkosten als Betrag oder „versandkostenfrei“, den Grundpreis (falls vorhanden) auf einen Blick mit dem Preis, die Energieeffizienzklasse mit Spektrum und Link zum Label (falls vorhanden), den Pflichthinweis (falls vorhanden) und den Anbieter mit Anschrift oder einem Weg dorthin. Preise sind Angaben der Händler zum Zeitpunkt price_as_of. Links in den Shop gehen über url (zählt den Klick ohne Personenbezug); Bilder nur von image, nie vom Shop direkt.

GET /api/v1/status

Stand des Dienstes: Version, index (aufbau | live), Zahl der Seiten im Index, der bestätigten Properties, Nachweise und Sitemaps.

Beispiel

curl -s "https://search.gemeinsamki.de/api/v1/search?q=gemeinsamki"
curl -s "https://search.gemeinsamki.de/api/v1/search?q=datenschutz&site=gemeinsamki.de&page=2"
curl -s "https://search.gemeinsamki.de/api/v1/status"

Suchanfragen zählen anonym in der Statistik (je Tag zusammengefasst, ohne IP-Adresse); das Betriebsprotokoll enthält nur den Pfad, nicht die Anfrage. Lizenz, Grenzen je Client und Schlüssel folgen.