API on 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:

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.

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-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"
 }
 ]
}

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:

Ü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.

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.

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).

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:

API on Seurch Dokumentation

Authentifizierung

Authentifizierung#

Einen Schlüssel erhalten#

Ratenlimits

Ratenlimits#

Wenn Sie ein Limit überschreiten#

Konventionen

Konventionen#

Gemeinsame Abfrageparameter#

Such-Endpunkte

Such-Endpunkte#

Web-Suche#

Bildsuche#

Ähnliche Bilder#

Karten

Karten#

Einen Ortsnamen geokodieren#

Koordinaten umgekehrt geokodieren#

Übersetzen

Übersetzen#

Text übersetzen#

Verfügbare Sprachen auflisten#

Sofortantworten & Karten

Sofortantworten & Wissenskarten#

Sofortantworten#

Meta-Endpunkte

Meta-Endpunkte#

Vorschläge#

Anbieterstatus#

Fehler

Fehler#

Statuscodes#

Fehlerbodies#

Validierungsfehler (400)#

Validierungsfehler (`400`)#