Seurch Dokumentation

Authentifizierung

Mon, 01 Jan 0001 00:00:00 +0000

Authentifizierung#

Jede API-Anfrage muss einen gültigen API-Schlüssel enthalten. Schlüssel werden pro Benutzer ausgestellt; eine Anfrage ohne einen erhält 401, und eine Anfrage mit einem schlechten oder widerrufenen Schlüssel wird abgelehnt.

Die API ist eine selbst-gehostete Funktion, daher werden Schlüssel auf Ihrer eigenen Instanz ausgestellt, nicht beim gehosteten seurch.eu-Dienst.

Einen Schlüssel erhalten#

Auf Ihrer Instanz:

In der Web-UI: Einstellungen → API-Schlüssel, erstellen Sie einen Schlüssel (optional benennen). Der vollständige Schlüssel wird einmal angezeigt; kopieren Sie ihn sofort.
Über die Befehlszeile (Administratoren): python manage.py create_api_key <benutzername> --name "mein Skript", siehe API-Schlüssel ausstellen.

Ein Schlüssel sieht aus wie:

Erste Schritte

Mon, 01 Jan 0001 00:00:00 +0000

Erste Schritte#

Anmelden#

Seurch erfordert ein Konto; es gibt keine anonyme Suche. Das Konto selbst kann jedoch anonym sein: Es werden nur ein Benutzername und ein Passwort benötigt; keine E-Mail-Adresse oder persönlichen Daten sind erforderlich (eine E-Mail ist optional und dient nur zum Zurücksetzen des Passworts, siehe Ihr Konto). Beim gehosteten Dienst sind Konten während der Alpha-Phase auf Einladung beschränkt; bei einer selbst gehosteten Instanz erstellt der Administrator die Konten.

Rufen Sie Ihre Seurch-Instanz auf (der gehostete Dienst ist unter seurch.eu verfügbar).
Klicken Sie auf Anmelden und geben Sie Ihren Benutzernamen und Ihr Passwort ein.
Sie gelangen auf die Such-Startseite.

Wenn Sie Ihr Passwort vergessen haben und eine E-Mail-Adresse zu Ihrem Konto hinzugefügt haben, verwenden Sie den Link Passwort vergessen?, um es zurückzusetzen. Ohne hinterlegte E-Mail kann ein verlorenes Passwort nicht wiederhergestellt werden; siehe Ihr Konto.

Voraussetzungen

Mon, 01 Jan 0001 00:00:00 +0000

Voraussetzungen#

Laufzeitumgebung#

Komponente	Hinweise
Eine Container-Laufzeitumgebung	Docker oder Podman, um das veröffentlichte Image auszuführen.
PostgreSQL	Die Anwendungsdatenbank. Jedes halbwegs aktuelle PostgreSQL (16+) funktioniert.
Ein Brave Search API-Schlüssel	Das Minimum für nützliche Ergebnisse; siehe Suchanbieter. Das kostenlose Kontingent reicht zum Starten.
Ausgehendes HTTPS	Der Server ruft vorgelagerte Anbieter ab; wenn Sie hinter einer Zulassungsliste sind, sehen Sie die Anbieter-Hosts.

Alles andere – Webserver, Bereitstellung statischer Dateien und Kompilierung der Übersetzungskataloge – ist im Image enthalten.

Ratenlimits

Mon, 01 Jan 0001 00:00:00 +0000

Ratenlimits#

Jeder API-Schlüssel hat sein eigenes Budget, das durch zwei zusammen geltende Limits durchgesetzt wird. Eine Anfrage muss beide erfüllen:

Limit	Standard	Zweck
Burst	`60/min`	Kurzfristiges Limit, schützt vorgelagerte Anbieter vor einem unkontrollierten Client.
Sustained	`5000/day`	Begrenzt das tägliche Gesamtvolumen.

Auf einer selbst-gehosteten Instanz sind diese mit API_THROTTLE_BURST und API_THROTTLE_SUSTAINED konfigurierbar; siehe Konfiguration.

Wenn Sie ein Limit überschreiten#

Das Überschreiten eines der beiden Limits gibt zurück:

HTTP 429 Too Many Requests

{ "detail": "Request was throttled. Expected available in 12 seconds." }

DRF enthält einen Retry-After-Hinweis in der Nachricht; warten Sie und versuchen Sie es nach der angegebenen Zeit erneut. Ein robuster Client sollte 429 mit exponentiellem Backoff behandeln.

Schnellstart

Mon, 01 Jan 0001 00:00:00 +0000

Schnellstart#

Der schnellste Weg zu einer laufenden Instanz ist das Docker-Image. Sie benötigen eine PostgreSQL-Datenbank und mindestens einen Brave Search API-Schlüssel.

Mit Docker#

docker run -p 8000:8000 \
 -e SECRET_KEY=ihr-langer-zufaelliger-schluessel \
 -e DATABASE_URL=postgres://benutzer:passwort@db-host:5432/seurch \
 -e ALLOWED_HOSTS=search.example.com \
 -e BRAVE_API_KEY=ihr-brave-schluessel \
 -e BRAVE_SUGGEST_API_KEY=ihr-brave-suggest-schluessel \
 -e MARGINALIA_API_KEY=public \
 seurch

Beim Start:

Wendet Datenbank-Migrationen an (kein Vorgang, wenn das Schema aktuell ist).
Stellt die App mit gunicorn (2 Worker) auf Port 8000 bereit.
Stellt eigene statische Dateien über WhiteNoise bereit (komprimiert und gehasht), kein separater Webserver oder CDN erforderlich.
Antwortet auf eine Gesundheitsprüfung unter /up.

Die Übersetzungskataloge und statischen Dateien werden beim Build kompiliert, sodass nichts weiteres gestartet werden muss.

Web-Suche

Mon, 01 Jan 0001 00:00:00 +0000

Web-Suche#

Der Web-Tab ist das Herzstück von Seurch. Er kann auf drei unabhängige Web-Indizes zurückgreifen und alles, was Sie aktivieren, in einer einzigen Rangliste zusammenführen.

Die drei Suchmaschinen#

Suchmaschine	Beschreibung
Brave	Ein großer unabhängiger Web-Index (unterstützt auch Bilder, Nachrichten und Videos).
Mojeek	Ein unabhängiger britischer Suchindex mit eigenem Crawler.
Marginalia	Ein nicht-kommerzieller Index, der sich auf das kleine, nicht-kommerzielle Web konzentriert.

Sie wählen die zu verwendenden Suchmaschinen unter Einstellungen → Suchmaschinen aus. Aktivieren Sie nur eine für eine einzige Quelle oder mehrere, um sie zu kombinieren. Alle drei sind standardmäßig aktiviert.

Konfiguration

Mon, 01 Jan 0001 00:00:00 +0000

Konfiguration#

Seurch wird vollständig über Umgebungsvariablen (in der Produktion) oder eine .env-Datei (in der Entwicklung) konfiguriert. Das Repository enthält eine .env.example, die jede Variable dokumentiert; diese Seite ist die Referenz.

Kern#

Variable	Zweck	Hinweise
`SECRET_KEY`	Django-Geheimschlüssel	In der Produktion erforderlich. Lang und zufällig.
`DEBUG`	Debug-Modus	In der Produktion `False` (der Standard) belassen.
`ALLOWED_HOSTS`	Kommagetrennte Hostnamen, die die App bedient	z.B. `search.example.com`.
`DATABASE_URL`	PostgreSQL-Verbindungs-URL	z.B. `postgres://user:pass@host:5432/seurch`.
`LOG_LEVEL`	Protokollierungsausführlichkeit	`DEBUG` / `INFO` / `WARNING` / `ERROR` (Standard `INFO`).

Suchanbieter#

Diese Schlüssel bestimmen, welche Suchmaschinen, Medien-Tabs und Wissenskarten verfügbar sind. Ein Anbieter ohne Schlüssel wird einfach ausgeblendet (nicht als defekt angezeigt). Vollständige Details unter Suchanbieter.

Konventionen

Mon, 01 Jan 0001 00:00:00 +0000

Konventionen#

Gemeinsame Abfrageparameter#

Die Such-Endpunkte akzeptieren einen gemeinsamen Satz von Parametern. Jeder entspricht einer Option, die die Website in ihrem Einstellungs-Cookie hält; hier sind sie in der URL explizit.

Parameter	Gilt für	Werte	Standard
`q`	alle Such-Endpunkte	Die Abfragezeichenkette (erforderlich)	—
`engine`	web, images, news, videos, cards	`brave`, `mojeek`, `marginalia` oder `all`; mehrere durch Komma oder Leerzeichen trennen	`all`
`safe`	web, images, news, videos, cards	`on` / `off` (`off`, `false`, `0`, `no` bedeuten alle off)	`on`
`lang`	die meisten Endpunkte	Ein Sprachcode, z.B. `de`, `en`	leer (auto)
`page`	web, images, news, videos	Seitennummer, `1`–`50`	`1`
`date`	web, news, videos	Zeitbereich: `d` (Tag), `w` (Woche), `m` (Monat), `y` (Jahr)	keiner

Hinweise:

Such-Tabs

Mon, 01 Jan 0001 00:00:00 +0000

Such-Tabs#

Neben dem Web-Tab hat Seurch dedizierte Tabs für Bilder, Nachrichten, Videos, Karten und Übersetzungen. Jeder führt Ihre Anfrage gegen Quellen aus, die für diese Art von Inhalt geeignet sind. Ein Tab erscheint nur, wenn die Instanz den benötigten Anbieter konfiguriert hat.

Bilder#

Bilderergebnisse stammen aus dem Brave-Bildindex, ergänzt durch Pixabay, wenn aktiviert. Ergebnisse werden als Rasteransicht von Vorschaubildern angezeigt.

Klicken Sie auf ein Bild, um eine Lightbox zu öffnen (ähnlich wie Google Bilder):

Sofortantworten

Mon, 01 Jan 0001 00:00:00 +0000

Sofortantworten#

Bei häufigen Dienstprogramm-Anfragen zeigt Seurch eine Sofortantwort ganz oben in den Web-Ergebnissen an, sodass Sie die Antwort erhalten, ohne durchklicken zu müssen. Dies ist im Geiste der Sofortantworten von DuckDuckGo.

Fast jede Sofortantwort wird lokal auf dem Server berechnet, ohne Beteiligung Dritter und ohne Weitersenden Ihrer Anfrage.

Was Sie fragen können#

Kategorie	Beispiel-Anfragen
Rechner	`2+2`, `sqrt(16)*3`, `15% von 200`
Einheitenumrechnung	`5 km in Meilen`, `100 f in c`, `2 Tassen in ml`
Basisumrechnung	`0xff in dezimal`, `255 in binär`
Farbe	`#4f46e5`, `rgb(255,128,0)`, `color picker`
Weltzeit	`Zeit in Tokio`, `wie spät ist es in New York`
QR-Code	`qr code https://example.com`
Hash / UUID	`md5 hallo`, `sha256 von test`, `uuid`
Passwort	`Passwortgenerator`, `sicheres Passwort`
Unix-Zeit	`unix timestamp`, `1700000000 in Datum`
Kodieren / Dekodieren	`base64 kodieren hallo`, `url dekodieren foo%20bar`
JSON / Regex	`json formatieren`, `regex tester`
HTTP / Ports	`http 404`, `port 443`
Zufallsgeneratoren	`2d6 würfeln`, `Münze werfen`, `Zufallszahl 1-100`
Timer	`Timer 5 Minuten`, `Stoppuhr`
Meine IP	`wie lautet meine IP`

Mehrsprachige Auslöser#

Sofortantworten funktionieren in sieben Sprachen: Englisch, Französisch, Deutsch, Spanisch, Italienisch, Portugiesisch und Niederländisch. Zum Beispiel funktionieren alle diese:

Such-Endpunkte

Mon, 01 Jan 0001 00:00:00 +0000

Such-Endpunkte#

Die Kernendpunkte: Web-, Bild-, Nachrichten- und Videosuche sowie der „ähnliche Bilder"-Helfer. Alle akzeptieren die gemeinsamen Parameter (q, engine, safe, lang, page, date).

Web-Suche#

GET /api/v1/web/?q=...

curl -H "Authorization: Api-Key seurch_sk_<präfix>.<geheimnis>" \
 "https://search.example.com/api/v1/web/?q=klima&engine=all&lang=de&date=w"

{
 "query": "klima",
 "tab": "web",
 "page": 1,
 "engine": ["brave", "mojeek", "marginalia"],
 "correction": "",
 "results": [
 {
 "title": "Klimawandel",
 "url": "https://example.org/klima",
 "description": "...",
 "display_url": "example.org",
 "favicon_url": "https://...",
 "age": "vor 2 Tagen",
 "source": "all",
 "source_label": "Brave, Mojeek, Marginalia",
 "sitelinks": []
 }
 ]
}

source / source_label — welche Suchmaschinen das Ergebnis zurückgegeben haben. brave / mojeek / marginalia für eine einzelne Suchmaschine, oder both / all für suchmaschinenübergreifende Übereinstimmung (source_label ist die lesbare Form).
correction — ein vorgeschlagener Rechtschreibvorschlag, oder "".

Bildsuche#

GET /api/v1/images/?q=...

{
 "query": "golden retriever",
 "tab": "images",
 "page": 1,
 "engine": ["brave"],
 "results": [
 {
 "title": "...",
 "url": "https://example.com/seite",
 "source": "example.com",
 "thumbnail": "https://.../thumb.jpg"
 }
 ]
}

Suchanbieter

Mon, 01 Jan 0001 00:00:00 +0000

Suchanbieter#

Seurch kombiniert Ergebnisse von mehreren unabhängigen Anbietern. Welche Tabs und Karten erscheinen, hängt davon ab, welche Schlüssel Sie setzen. Ein Anbieter ohne Schlüssel wird ausgeblendet; der betroffene Tab oder die Karte erscheint einfach nicht, anstatt einen Fehler anzuzeigen.

Alle vorgelagerten Aufrufe erfolgen serverseitig; Schlüssel werden nie an den Browser weitergegeben.

Diese Seite bietet den Überblick darüber, welcher Schlüssel was aktiviert. Schritt-für-Schritt-Anweisungen zur Anmeldung bei jedem Anbieter finden Sie unter API-Schlüssel erhalten.

API-Schlüssel erhalten

Mon, 01 Jan 0001 00:00:00 +0000

API-Schlüssel erhalten#

Schritt-für-Schritt-Anleitungen zum Erhalten des Schlüssels jedes Anbieters. Keiner ist erforderlich, um Seurch zu starten, aber mindestens eine Web-Suchmaschine (Brave ist am einfachsten) wird für nützliche Ergebnisse benötigt. Jeder Anbieter, den Sie überspringen, blendet seinen Tab oder seine Karte einfach aus; unter Suchanbieter finden Sie, was jeder aktiviert.

Sobald Sie einen Schlüssel haben, setzen Sie die entsprechende Umgebungsvariable (siehe Konfiguration) und starten Sie die App neu.

Alle haben ein kostenloses Kontingent, das für eine persönliche oder kleine Team-Instanz großzügig genug ist; Seurch cached aggressiv und ruft die kostenpflichtigen Karten-APIs nur auf, wenn eine Anfrage tatsächlich übereinstimmt. Die geteilten Schlüssel (public für Marginalia, anonymes Stack Exchange) benötigen überhaupt keine Anmeldung.

Karten

Mon, 01 Jan 0001 00:00:00 +0000

Karten#

Geokodieren Sie einen Ortsnamen oder führen Sie eine umgekehrte Geokodierung eines Koordinatenpaars durch, unter Verwendung von OpenStreetMaps Nominatim. Kein Anbieter-Schlüssel erforderlich.

GET /api/v1/maps/

Einen Ortsnamen geokodieren#

GET /api/v1/maps/?q=<ort>&limit=<n>&lang=<code>

q — der Ort oder die Adresse zum Nachschlagen (erforderlich in diesem Modus).
limit — maximale Anzahl Ergebnisse, 1–50 (Standard 10).
lang — bevorzugte Sprache für Namen.

curl -H "Authorization: Api-Key seurch_sk_<präfix>.<geheimnis>" \
 "https://search.example.com/api/v1/maps/?q=Brandenburger+Tor&limit=1"

{
 "query": "Brandenburger Tor",
 "places": [
 {
 "name": "Brandenburger Tor",
 "display_name": "Brandenburger Tor, Berlin, Deutschland",
 "lat": 52.5163,
 "lon": 13.3777,
 "category": "tourism",
 "type": "attraction",
 "addresstype": "tourism",
 "importance": 0.85,
 "embed_url": "https://www.openstreetmap.org/export/embed.html?...",
 "mini_embed_url": "https://...",
 "osm_url": "https://www.openstreetmap.org/...",
 "directions_url": "https://www.openstreetmap.org/directions?...",
 "geo_uri": "geo:52.5163,13.3777"
 }
 ]
}

Koordinaten umgekehrt geokodieren#

Übergeben Sie lat und lon anstelle von q:

Wissenskarten

Mon, 01 Jan 0001 00:00:00 +0000

Wissenskarten#

Wenn Ihre Web-Suche (erste Seite) ein bekanntes Thema betrifft, zeigt Seurch bis zu drei Wissenskarten neben den Ergebnissen an – eine Schnellzusammenfassung, sodass Sie oft nicht durchklicken müssen.

Die Karten#

Karte	Quelle	Zeigt
Wikipedia	Wikipedia	Eine Zusammenfassung, ein Bild und einen Link zum Thema. Dies ist die Ankerkarte; sie hilft auch zu erkennen, was die anderen Karten zeigen sollen.
Film / TV	TMDB	Details zu einem Film oder einer TV-Sendung: Poster, Bewertung, Jahr, Übersicht.
Orte	TripAdvisor	Ein Restaurant, Hotel oder eine Attraktion: Bewertung, Adresse (die zur Karte verlinkt) und ein Link.
Q&A	Stack Exchange	Die beste Frage und Antwort für eine technische Anfrage.

Wie sie ausgewählt werden#

Seurch zeigt eine Karte nur dann an, wenn Ihre Anfrage wirklich zu dieser Art von Thema passt:

Bangs

Mon, 01 Jan 0001 00:00:00 +0000

Bangs#

Bangs sind !Verknüpfungen, die Sie in das Suchfeld eingeben, um eine Anfrage direkt zu einer anderen Website oder einem anderen Seurch-Tab zu senden. Seurch versteht das weit verbreitete DuckDuckGo-Bang-Vokabular mit Tausenden von Websites sowie einige eigene.

Die Bang-Definitionen stammen aus dem Open-Source-Bang-Repository von Kagi, derselben community-gepflegten !bang-Liste, die Kagi veröffentlicht. Selbst-Hoster können diese mit make bangs aktualisieren; siehe Wartung.

Ein Bang kann überall in der Anfrage stehen; der Rest des Textes sind die Suchbegriffe.

Übersetzen

Mon, 01 Jan 0001 00:00:00 +0000

Übersetzen#

Übersetzen Sie Text zwischen Sprachen, betrieben vom LibreTranslate der Instanz. Dieser Endpunkt akzeptiert GET oder POST; verwenden Sie POST, um langen Text aus der URL und den Logs herauszuhalten.

GET /api/v1/translate/
POST /api/v1/translate/

Text übersetzen#

Parameter	Erforderlich	Bedeutung
`q` (oder `text`)	ja	Der zu übersetzende Text
`target`	ja	Zielsprachcode (z.B. `de`)
`source`	nein	Quellsprachcode; standardmäßig `auto` (erkennen)

# GET
curl -H "Authorization: Api-Key seurch_sk_<präfix>.<geheimnis>" \
 "https://search.example.com/api/v1/translate/?q=hello&target=de"

# POST (besser für langen Text)
curl -X POST -H "Authorization: Api-Key seurch_sk_<präfix>.<geheimnis>" \
 -d "q=hello world" -d "target=de" \
 "https://search.example.com/api/v1/translate/"

{
 "source": "auto",
 "target": "de",
 "translated_text": "hallo welt",
 "detected_lang": "en"
}

detected_lang wird nur ausgefüllt, wenn source auto war (sonst leer).
Wenn Übersetzung auf der Instanz nicht konfiguriert ist, gibt der Endpunkt 503 zurück mit {"detail": "Translation is unavailable or not configured on this deployment."}.

Verfügbare Sprachen auflisten#

GET /api/v1/translate/languages/

{
 "languages": [
 { "code": "en", "name": "English" },
 { "code": "de", "name": "German" }
 ]
}

Die Liste spiegelt wider, was die verbundene LibreTranslate-Instanz anbietet; siehe Übersetzung für die Selbst-Hosting-Seite.

Übersetzung

Mon, 01 Jan 0001 00:00:00 +0000

Übersetzung (LibreTranslate)#

Der Übersetzen-Tab wird von LibreTranslate betrieben, einem Open-Source, selbst-hostbaren Maschinenübersetzungsserver. Seurch ruft ihn serverseitig auf; kein Drittanbieter-Übersetzungsdienst ist beteiligt.

Den Tab aktivieren#

Zeigen Sie Seurch mit LIBRETRANSLATE_URL auf eine LibreTranslate-Instanz:

LIBRETRANSLATE_URL=http://libretranslate:5000

Gesetzt: Der Übersetzen-Tab (und seine Einstellung) erscheinen mit den Sprachen, die diese Instanz anbietet.
Nicht gesetzt: Der Übersetzen-Tab und seine Einstellung werden vollständig deaktiviert.

LibreTranslate betreiben#

Der Entwicklungs-Stack startet automatisch ein lokales LibreTranslate (make up startet eines unter http://localhost:5000). Für die Produktion betreiben Sie Ihr eigenes, zum Beispiel:

Benutzer & Zugang

Mon, 01 Jan 0001 00:00:00 +0000

Benutzer & Zugang#

Seurch ist nur mit Anmeldung zugänglich und hat keine öffentliche Registrierung; als Administrator kontrollieren Sie, wer ein Konto hat. Dies hält eine Instanz privat für Ihre Benutzer.

Konten erstellen#

Erstellen Sie Benutzer mit Djangos Standard-Verwaltungsbefehl:

# Docker
docker exec -it <container> python manage.py createsuperuser

# Aus dem Quellcode
make superuser

createsuperuser erstellt ein Admin-Konto; für gewöhnliche Benutzer können Sie diese auf die gleiche Weise erstellen (oder über das Django-Admin, sobald Sie einen Superuser haben). Jedes Konto benötigt einen Benutzernamen und ein Passwort; eine E-Mail ist optional (siehe unten).

Einstellungen

Mon, 01 Jan 0001 00:00:00 +0000

Einstellungen#

Öffnen Sie Einstellungen von der Startseite oder dem Menü aus, um Seurch anzupassen. Ihre Einstellungen werden automatisch mit Ihrem Konto synchronisiert und auf jedem Gerät wiederhergestellt, auf dem Sie sich anmelden. Sie werden auch in Ihrem Browser gespeichert, sodass sie auch vor der Anmeldung gelten.

Was Sie ändern können#

Einstellung	Optionen	Standard
Suchmaschinen	Beliebige Kombination aus Brave / Mojeek / Marginalia	Alle aktiviert
SafeSearch	Ein / Aus	Ein
Suchsprache	Auto oder eine der sieben UI-Sprachen	Auto (Ihr Browser)
Oberflächensprache	Auto oder eine der sieben UI-Sprachen	Auto
Design	System / Hell / Dunkel	System
Links öffnen	Gleicher Tab / Neuer Tab	Gleicher Tab
Bilder proxyen	Ein / Aus	Aus
Wissenskarten Lazy-Load	Ein / Aus	Ein
Datenquellen	Pro-Anbieter Ein/Aus-Schalter	Alle aktiviert

Suchmaschinen#

Wählen Sie, welche Web-Indizes Seurch abfragt und zusammenführt; siehe Web-Suche. Hier verwalten Sie auch Ihre blockierten Websites und benutzerdefinierten Bangs.

Sofortantworten & Karten

Mon, 01 Jan 0001 00:00:00 +0000

Sofortantworten & Wissenskarten#

Diese zwei Endpunkte spiegeln die Inline-Antworten und Seitenpanel der Website wider. Da ihr Inhalt je nach Antworttyp und Anbieter variiert, geben sie anbietergeformtes JSON zurück statt eines festen Schemas pro Feld; behandeln Sie die Strukturen als Daten und lesen Sie die Felder, die Sie benötigen.

Sofortantworten#

GET /api/v1/instant/?q=...

Gibt die Sofortantwort für eine Dienstprogramm-Anfrage zurück (Mathematik, Einheits-/Basis-/Farbumrechnung, Wetter, Währung, Weltzeit, Hashes, QR, „meine IP", …), oder null, wenn die Anfrage keine ist, die Seurch inline beantwortet.

API-Schlüssel

Mon, 01 Jan 0001 00:00:00 +0000

API-Schlüssel#

Benutzer greifen auf die öffentliche API mit benutzerspezifischen API-Schlüsseln zu. Benutzer können ihre eigenen Schlüssel in der Web-UI verwalten (Einstellungen → API-Schlüssel), und Sie können sie über die Befehlszeile verwalten.

Wie Schlüssel gespeichert werden#

Ein Schlüssel sieht aus wie seurch_sk_<präfix>.<geheimnis>:

Das Präfix (8 Zeichen) wird im Klartext für die schnelle Suche gespeichert.
Nur ein SHA-256-Hash des Geheimnisses wird gespeichert, nie das Geheimnis selbst.

Daher wird der vollständige Wert eines Schlüssels genau einmal angezeigt, bei der Erstellung, und kann danach nicht wiederhergestellt, nur widerrufen werden.

Ihr Konto

Mon, 01 Jan 0001 00:00:00 +0000

Ihr Konto#

Anmelden#

Seurch ist nur mit Anmeldung nutzbar; jede Suche findet unter Ihrem Konto statt, und es gibt kein öffentliches Registrierungsformular. Beim gehosteten Dienst sind Konten während der Alpha-Phase nur auf Einladung erhältlich; bei einer selbst gehosteten Instanz erstellt der Administrator die Konten.

Ihr Konto kann anonym sein: Es braucht nur einen Benutzernamen und ein Passwort, keine E-Mail oder anderen persönlichen Daten. Es gibt keine anonyme Suche (Sie sind immer angemeldet), aber das dahinterstehende Konto muss Sie nicht identifizieren.

Meta-Endpunkte

Mon, 01 Jan 0001 00:00:00 +0000

Meta-Endpunkte#

Hilfsprogramme für Autocomplete, Anbieter-Gesundheit, Schlüssel-Inspektion und Endpunkt-Entdeckung. Die Wurzel, status/ und key/ zählen nicht zu Ihrer monatlichen Such-Nutzung (sie zählen noch gegen das rohe Ratenlimit).

Vorschläge#

Autocomplete-Vorschläge der Suchleiste für eine Anfrage. (Zählt als eine Suche.)

GET /api/v1/suggest/?q=...

curl -H "Authorization: Api-Key seurch_sk_<präfix>.<geheimnis>" \
 "https://search.example.com/api/v1/suggest/?q=klim"

{
 "query": "klim",
 "suggestions": ["klima", "klimawandel", "klimaschutz"]
}

Anbieterstatus#

Aktueller Aufwärts-/Abwärtsstatus jedes konfigurierten vorgelagerten Anbieters, die Daten hinter der /status-Seite. (Zählt nicht zur Nutzung.)

GET /api/v1/status/

{
 "providers": [
 {
 "slug": "brave",
 "name": "Brave",
 "group": "web",
 "monitor": "query",
 "state": "up",
 "checked_at": "2026-06-30T09:00:00Z",
 "last_ok_at": "2026-06-30T09:00:00Z",
 "last_error": "",
 "source": ""
 }
 ]
}

monitor — wie der Status ermittelt wurde: query (aus echten Suchen beobachtet) oder probe (aktive Gesundheitsprüfung).
state — up, down oder unknown (noch nichts beobachtet).

Ein Anbieter ohne konfigurierten API-Schlüssel wird ausgelassen (ausgeblendet, nicht als ausgefallen angezeigt).

Datenschutz

Mon, 01 Jan 0001 00:00:00 +0000

Datenschutz#

Seurch ist als datenschutzfreundliche Alternative zu überwachungsfinanzierten Suchmaschinen konzipiert. Hier ist, was das in der Praxis bedeutet.

Was Seurch nicht tut#

Kein Tracking. Seurch verfolgt Sie nicht im Web oder sitzungsübergreifend, um ein Profil zu erstellen.
Keine Werbung. Es gibt keine Werbung, also keinen Anreiz, Sie zu profilieren.
Kein Datenverkauf. Ihre Suchen sind kein Produkt, das an jemanden verkauft wird.

Wie Ihre Anfragen behandelt werden#

Suchen laufen serverseitig. Seurch spricht in Ihrem Namen mit vorgelagerten Anbietern (Brave, Mojeek, Marginalia und andere), sodass diese Anbieter Ihren Browser oder Ihre IP nicht sehen – sie sehen Seurchs Server.
Anbieter-API-Schlüssel erreichen Ihren Browser nie. Alle vorgelagerten Aufrufe erfolgen auf dem Server.
Bilder-Proxy (optional, in den Einstellungen) leitet Vorschaubilder über den Seurch-Server, sodass Quellwebsites Ihren Browser ebenfalls nicht sehen.
Ergebnisse werden kurzzeitig auf dem Server gecacht, um die Geschwindigkeit zu halten und die Last bei Anbietern zu reduzieren; der Cache ist auf die Anfrage, nicht auf Sie, bezogen.

Ihre Daten#

Ihre Einstellungen werden mit Ihrem Konto synchronisiert, damit sie auf allen Geräten verfügbar sind. Sie können sie exportieren oder löschen.
Ihre E-Mail, falls Sie eine hinzufügen, wird nur zum Zurücksetzen des Passworts verwendet; siehe Ihr Konto.

Wo der Dienst betrieben wird#

Der gehostete Dienst wird in der Europäischen Union unter europäischem Datenschutzrecht betrieben. Da die Suchmaschine Open Source ist, kann jeder ihre Funktionsweise prüfen oder eine eigene Kopie betreiben und der einzige Betreiber sein, der jemals ihre Daten berührt.

Fehler

Mon, 01 Jan 0001 00:00:00 +0000

Fehler#

Die API verwendet Standard-HTTP-Statuscodes und gibt einen JSON-Body zurück, der das Problem beschreibt.

Statuscodes#

Code	Bedeutung	Typische Ursache
`200`	OK	Erfolgreiche Anfrage.
`400`	Ungültige Anfrage	Ein schlechter Parameter, z.B. ein fehlendes `q`, ein nicht-ganzzahliges `page` oder ein unbekanntes `engine`.
`401`	Nicht autorisiert	Kein API-Schlüssel gesendet (oder kein erkannter Auth-Header).
`403`	Verboten	Schlüssel gehört zu einem deaktivierten Konto.
`429`	Zu viele Anfragen	Ein Ratenlimit wurde überschritten.
`503`	Dienst nicht verfügbar	Ein abhängiger Dienst ist nicht konfiguriert, z.B. Übersetzung, wenn LibreTranslate nicht gesetzt ist.

Fehlerbodies#

Validierungsfehler (`400`)#

Feldgebundene Nachrichten:

Wartung

Mon, 01 Jan 0001 00:00:00 +0000

Wartung#

Seurch benötigt wenig laufende Pflege, aber einige Verwaltungsbefehle halten es ordentlich und aktuell. Führen Sie diese nach einem Zeitplan aus (ein Cron-Job, ein systemd-Timer oder die Funktion für geplante Aufgaben Ihres Orchestrators). Führen Sie jeden im Container aus (docker exec <container> python manage.py …) oder via make / uv run aus dem Quellcode.

Geplante Aufgaben#

Befehl	Was er tut	Empfohlener Zeitplan
`clear_expired_cache`	Löscht abgelaufene Suchergebnis-Cache-Zeilen	Täglich
`check_provider_health`	Prüft Anbieter mit einem kostenlosen Gesundheits-Endpunkt, damit `/status` aktuell bleibt, ohne kostenpflichtiges Kontingent zu verbrauchen	Alle ~10 Minuten
`refresh_currency`	Aktualisiert gecachte Wechselkurse und bereinigt den Sofortantwort-Cache	Täglich (optional, aktualisiert sich auch bei Bedarf selbst)

Ein Cron-Beispiel:

Browser einrichten

Mon, 01 Jan 0001 00:00:00 +0000

Browser einrichten#

Sie können Seurch als Suchmaschine festlegen, die beim Tippen in der Adressleiste oder im Suchfeld des Browsers ausgelöst wird. Diese Seite behandelt alle gängigen Browser, einschließlich der Einrichtung von Seurch speziell für private / Inkognito-Fenster.

Die Such-URL#

Wenn ein Browser nach der URL Ihrer Suchmaschine fragt, verwenden Sie:

https://seurch.eu/?q=%s

Ersetzen Sie seurch.eu durch den Hostnamen Ihrer eigenen Instanz, wenn Sie selbst hosten.

Das %s ist ein Platzhalter, den der Browser durch Ihre Suchanfrage ersetzt. Einige Browser nennen dieses Feld Such-URL oder Anfrage-URL; das Format ist identisch.

Produktionshinweise

Mon, 01 Jan 0001 00:00:00 +0000

Produktionshinweise#

Einige wichtige Punkte, wenn Sie Seurch für echte Benutzer betreiben.

Das Image#

Stellt die App mit gunicorn (2 Worker) auf Port 8000 bereit.
Stellt eigene statische Dateien über WhiteNoise bereit, komprimiert und gehasht, sodass Sie keinen separaten statischen Dateiserver oder CDN benötigen.
Kompiliert Übersetzungskataloge und sammelt statische Dateien zur Build-Zeit.
Führt Datenbank-Migrationen beim Start aus.

Reverse-Proxy und TLS#

Stellen Sie einen TLS-terminierenden Reverse-Proxy davor (Caddy, nginx, Traefik, …) und leiten Sie an Port 8000 weiter. Setzen Sie:

Seurch Dokumentation

Authentifizierung

Authentifizierung#

Einen Schlüssel erhalten#

Erste Schritte

Erste Schritte#

Anmelden#

Voraussetzungen

Voraussetzungen#

Laufzeitumgebung#

Ratenlimits

Ratenlimits#

Wenn Sie ein Limit überschreiten#

Schnellstart

Schnellstart#

Mit Docker#

Web-Suche

Web-Suche#

Die drei Suchmaschinen#

Konfiguration

Konfiguration#

Kern#

Suchanbieter#

Konventionen

Konventionen#

Gemeinsame Abfrageparameter#

Such-Tabs

Such-Tabs#

Bilder#

Sofortantworten

Sofortantworten#

Was Sie fragen können#

Mehrsprachige Auslöser#

Such-Endpunkte

Such-Endpunkte#

Web-Suche#

Bildsuche#

Ähnliche Bilder#

Suchanbieter

Suchanbieter#

API-Schlüssel erhalten

API-Schlüssel erhalten#

Karten

Karten#

Einen Ortsnamen geokodieren#

Koordinaten umgekehrt geokodieren#

Wissenskarten

Wissenskarten#

Die Karten#

Wie sie ausgewählt werden#

Bangs

Bangs#

Übersetzen

Übersetzen#

Text übersetzen#

Verfügbare Sprachen auflisten#

Übersetzung

Übersetzung (LibreTranslate)#

Den Tab aktivieren#

LibreTranslate betreiben#

Benutzer & Zugang

Benutzer & Zugang#

Konten erstellen#

Einstellungen

Einstellungen#

Was Sie ändern können#

Suchmaschinen#

Sofortantworten & Karten

Sofortantworten & Wissenskarten#

Sofortantworten#

API-Schlüssel

API-Schlüssel#

Wie Schlüssel gespeichert werden#

Ihr Konto

Ihr Konto#

Anmelden#

Meta-Endpunkte

Meta-Endpunkte#

Vorschläge#

Anbieterstatus#

Validierungsfehler (`400`)#