In den letzten Jahren hat sich SearXNG als beliebte, datenschutzfreundliche Alternative zu klassischen Suchmaschinen etabliert. Doch wer die JSON-basierte Such-API der Software nutzt, stößt oft auf ein frustrierendes Phänomen: Was auf einer Instanz problemlos funktioniert, scheitert auf einer anderen – ohne dass im Code Änderungen vorgenommen wurden.
Diese Diskrepanz führt regelmäßig zu Verwirrung bei Entwickler:innen, die Tools wie terminalbasierte Browser oder CLI-Anwendungen auf SearXNG aufbauen. Ein typischer Hinweis darauf ist die Formulierung „Ich habe Probleme, die SearXNG-Verbindung zuverlässig zu parsen“. Doch der Fehler liegt selten im Code selbst, sondern in einer falschen Annahme: dass alle öffentlichen SearXNG-Instanzen die JSON-Ausgabe standardmäßig unterstützen.
Warum die JSON-Ausgabe nicht überall verfügbar ist
SearXNG ist standardmäßig so konfiguriert, dass die JSON-Ausgabe deaktiviert ist. In der zentralen Konfigurationsdatei settings.yml wird dies über die Liste search.formats gesteuert. Ein Auszug aus der Standardkonfiguration sieht wie folgt aus:
search:
formats:
- html
# - json # Kommentiert oder nicht vorhandenOhne explizite Aktivierung der JSON-Ausgabe in dieser Liste antwortet eine Instanz auf eine Anfrage wie GET /search?q=test&format=json mit einem HTTP 403 Forbidden. Dies ist kein Fehler, sondern eine bewusste Entscheidung der Instanzbetreiber:innen. Der Grund? JSON-Anfragen lassen sich einfacher automatisieren als HTML-Seiten, was das Risiko von Missbrauch und unerwünschtem Traffic erhöht. Viele öffentliche Instanzen deaktivieren daher die JSON-Unterstützung gezielt, um ihre Server vor übermäßiger Last zu schützen.
Nicht alle Instanzen antworten mit einem klaren Fehler
Während einige Instanzen – wie searx.be – einen sauberen 403-Statuscode zurückgeben, reagieren andere mit noch tückischeren Antworten. Bei Tests am 2. Juli 2026 zeigten mehrere öffentliche Instanzen ein unerwartetes Verhalten:
- `baresearch.org` und `search.bus-hit.me`: Beide lieferten einen HTTP 200 OK-Status, doch der Antwortkörper enthielt keine JSON-Daten, sondern eine HTML-Seite mit einer Anti-Bot-Herausforderung (z. B. „Stellen Sie sicher, dass Sie kein Bot sind!“).
- `searx.stream`: Diese Instanz antwortete mit einem HTTP 307 Temporary Redirect, was ohne korrekte Weiterverarbeitung ebenfalls zu Fehlern führt.
Für Entwickler:innen bedeutet dies: Ein einfaches response.raise_for_status() in Python erkennt das Problem nicht, da der Statuscode 200 ist. Erst beim Versuch, die Antwort als JSON zu parsen (response.json()), tritt ein ValueError oder JSONDecodeError auf – und zwar genau dann, wenn die HTML-Seite mit <!DOCTYPE html> beginnt. Noch problematischer wird es, wenn die Fehlerbehandlung so implementiert ist, dass sie den Fehler einfach ignoriert und „keine Ergebnisse gefunden“ zurückgibt. In diesem Fall ist der Fehler nicht mehr nachvollziehbar.
So gehst du das Problem richtig an
1. Vermeide die Annahme, dass alle Instanzen gleich funktionieren
Verwende nicht einfach eine zufällig ausgewählte öffentliche Instanz als festen Endpunkt in deinem Code. Stattdessen solltest du eine Liste vertrauenswürdiger Instanzen nutzen, die explizit JSON unterstützen. Eine solche Liste wird von searx.space gepflegt, das regelmäßig überprüft, welche Formate von welchen Instanzen angeboten werden. Filtere deine Anfragen gezielt nach Instanzen, die json in ihrer unterstützten Ausgabeformaten auflisten.
2. Prüfe den Content-Type der Antwort vor dem Parsen
Bevor du die Antwort einer SearXNG-API-Anfrage verarbeitest, solltest du den Content-Type-Header der HTTP-Antwort überprüfen. Eine korrekte JSON-Antwort sollte den Header Content-Type: application/json enthalten. Ist stattdessen Content-Type: text/html gesetzt, ist klar, dass die Instanz keine JSON-Daten liefert – und du kannst eine entsprechende Fehlermeldung ausgeben, statt den Parser zu starten. Ein minimaler Python-Codeausschnitt dafür sähe so aus:
import requests
response = requests.get(
"
params={"q": "test", "format": "json"}
)
if response.status_code == 200 and "application/json" in response.headers.get("Content-Type", ""):
data = response.json()
print(data)
else:
print("Diese Instanz unterstützt kein JSON oder liefert eine ungültige Antwort.")3. Nutze eine eigene Instanz für zuverlässige Ergebnisse
Wenn dein Tool oder deine Anwendung regelmäßig auf SearXNG zugreift, solltest du in Betracht ziehen, eine eigene Instanz zu betreiben. Öffentliche SearXNG-Instanzen werden von Freiwilligen betrieben, die die Serverkosten und den Traffic selbst tragen. Die Nutzung solcher Instanzen als kostenlose API-Infrastruktur für automatisierte Abfragen ist genau das, was viele Betreiber:innen dazu veranlasst, die JSON-Ausgabe zu deaktivieren.
Die Einrichtung einer eigenen Instanz ist mit modernen Tools wie Docker denkbar einfach. Ein Beispiel für eine minimale docker-compose.yml-Konfiguration:
version: '3.8'
services:
searxng:
image: searxng/searxng:latest
ports:
- "8888:8888"
environment:
- BASE_URL=
volumes:
- ./settings.yml:/etc/searxng/settings.ymlNach dem Start kannst du die JSON-Ausgabe in der settings.yml explizit aktivieren und hast so eine zuverlässige, kontrollierbare Umgebung für deine Anwendung.
4. Lies die Dokumentation und teste vor der Implementierung
SearXNG selbst weist in seiner offiziellen Dokumentation darauf hin, dass die JSON-Ausgabe standardmäßig deaktiviert ist. Ein Blick in die Dokumentation oder ein kurzer Test mit verschiedenen öffentlichen Instanzen vor der Implementierung hätte viele dieser Probleme von vornherein vermeiden können.
Fazit: Transparenz und Eigenverantwortung sind entscheidend
Die Probleme, die bei der Nutzung der SearXNG-JSON-API auftreten, sind kein Zeichen für eine fehlerhafte Implementierung der Software selbst. Vielmehr handelt es sich um ein klassisches Beispiel dafür, wie schnell falsche Annahmen zu unerwartetem Verhalten führen können. Entwickler:innen sollten sich bewusst sein, dass öffentliche Instanzen unterschiedliche Konfigurationen und Einschränkungen haben – und dass die JSON-Ausgabe nur eine von vielen Möglichkeiten ist.
Wer auf Nummer sicher gehen will, setzt auf eine eigene Instanz oder nutzt vertrauenswürdige Listen wie searx.space. So vermeidest du nicht nur technische Probleme, sondern trägst auch dazu bei, die Last auf den öffentlichen Servern fair zu verteilen. SearXNG bleibt damit nicht nur eine leistungsfähige Suchlösung, sondern auch ein Projekt, das von der Community getragen wird – und genau das sollte auch in der eigenen Nutzung respektiert werden.
KI-Zusammenfassung
SearXNG’nin JSON çıktısını neden bazı örneklerde devre dışı bıraktığını, sessiz başarısızlıkların arkasındaki teknik nedenleri ve bu sorunu çözmek için uygulayabileceğiniz yöntemleri keşfedin.
