Leitfaden zur SERP-Scraping-API: Google, Bing, DuckDuckGo, Yandex

Die SERP-API von WebScrapingAPI ist ein serverseitiger Endpunkt, der eine Suchanfrage, eine Suchmaschine und den Marktkontext entgegennimmt und anschließend die Ergebnisseite als Daten zurückgibt. Google und Bing liefern geparste JSON-Sammlungen zurück. DuckDuckGo und Yandex liefern einen JSON-Umschlag zurück, dessen search_results Feld den SERP-HTML-Code enthält, den Ihr Code extrahieren kann.

Diese Aufteilung ist das Wichtigste, was Sie verstehen müssen, bevor Sie Code schreiben. Bei Google und Bing lesen Sie benannte Sammlungen wie organic[] und related[]. Bei DuckDuckGo und Yandex erhalten Sie die Rohseite und entscheiden selbst, welche Informationen Sie daraus extrahieren möchten. Ihr Speichermodell, Ihre Tests und Ihre Wartungsarbeiten richten sich danach, auf welcher Seite dieser Grenze sich eine Suchmaschine befindet.

Die API deckt vier Suchmaschinenfamilien ab: Google, Bing, DuckDuckGo und Yandex. Google verfügt neben der Standardsuche zudem über sieben spezialisierte Suchmaschinen: Async-Suche, Maps, Maps-Bewertungen, Hotels, Flüge, Trends und Bildersuche. Teams nutzen diese für die Überwachung von Rankings und SERP-Funktionen, die Präsenz von Marken und Publishern, angezeigte bezahlte Platzierungen sowie für Marktforschung über Themen und Publisher hinweg.

• WebScrapingAPI übernimmt: die Validierung von Anfragen und die Ausführung durch die Suchmaschinen, die Infrastruktur für den Suchzugriff, die Sammlung und Aufbereitung der analysierten Ergebnisse (sofern dokumentiert), die Bereitstellung des JSON-Envelopes für HTML-Suchmaschinen sowie die Wartung des Verhaltens der unterstützten Endpunkte.
• Ihr Team ist verantwortlich für: Abfragegruppen, Märkte, Sprachen und Geräte sowie für die Zeitplanung, Wiederholungsversuche auf API-Ebene, die Extraktion aus HTML-Envelopes, die Speicherung, die Berechnung von Rankings, Warnmeldungen sowie Richtlinien zur Datennutzung und -aufbewahrung.

Für die Analyse ist noch eine weitere Grenze von Bedeutung. Die API definiert keinen universellen Rang. Jedes Ergebnis beschreibt eine Suchanfrage in einem Markt, auf einem Gerät und zu einem bestimmten Zeitpunkt; behalten Sie diesen Kontext daher bei jeder Zeile, die Sie speichern, im Blick. Möchten Sie die API mit anderen APIs zum Zeitpunkt der Anfrage vergleichen? Sehen Sie sich an, wie sich die SERP-API im Vergleich zu den anderen Web-Access-APIs einordnet.

Erstellen Sie ein Konto, abonnieren Sie die SERP-API im Dashboard und kopieren Sie Ihren API-Schlüssel in eine Umgebungsvariable. Senden Sie anschließend eine GET-Anfrage an https://serpapi.webscrapingapi.com/v2 mit api_key, engine=googleund q auf Ihr Suchwort setzen. Lassen Sie Ihre HTTP-Bibliothek die Parameter kodieren und bewahren Sie den Schlüssel auf dem Server auf.

1. Registriere ein WebScrapingAPI-Konto.
2. Abonnieren Sie die SERP-API im Dashboard. Die Testversion umfasst 100 Google-Suchen.
3. Speichern Sie den Schlüssel in Ihrer Shell oder Ihrem Secret-Manager: export WSA_API_KEY=...
4. Senden Sie die Anfrage mit einem der folgenden Snippets.

Die Anfrage hat für jede Suchmaschine denselben Aufbau. Nur engine, das Abfragefeld und die Kontextparameter ändern sich; sobald dieser Aufruf also funktioniert, ist die Anpassung an jede andere Suchmaschine nur noch eine Frage der Parameter.

curl. Die --data-urlencode Flags kodieren jeden Wert, und --max-time 120 legt ein explizites Client-Timeout fest:

# Google, parsed JSON, US English, mobile
EP="https://serpapi.webscrapingapi.com/v2"
curl --get --fail-with-body --max-time 120 "$EP" \
  --data-urlencode "api_key=$WSA_API_KEY" \
  --data-urlencode "engine=google" \
  --data-urlencode "q=running shoes" \
  --data-urlencode "gl=us" --data-urlencode "hl=en" --data-urlencode "device=mobile"

Python. Dieser kleine Client liest den Schlüssel aus der Umgebung, übergibt jeden Wert an das params Argument, sodass Requests diese für Sie codiert, führt Wiederholungsversuche gemäß der Fehlerbehandlung durch und protokolliert die Nutzungs-Header. Die folgenden Abschnitte zu Bing und zur Fehlerbehandlung greifen darauf zurück.

"""Minimal WebScrapingAPI SERP API client: env-var key, jittered retries, usage headers.

Usage:
  export WSA_API_KEY=...                       # never hardcode the key
  python wsa_serp.py google "running shoes" gl=us hl=en device=mobile
  python wsa_serp.py bing "coffee roasters" mkt=en-US cc=us lang=en
  python wsa_serp.py yandex "pizza" lr=213 p=0
  python wsa_serp.py google "running shoes" gl=us --dry-run   # print the request, no call
"""
import os
import random
import sys
import time

import requests

ENDPOINT = "https://serpapi.webscrapingapi.com/v2"
# Most engines take their main input in q. These don't (see the engine table).
QUERY_FIELD = {"yandex": "text", "google_maps_reviews": "fid", "google_reverse_image": "url"}
RETRYABLE = {429, 500, 502, 503}   # back off with jitter, then retry
FINAL = {400, 401}                 # fix the key, plan, or parameters; never retry


def build_params(engine, query, **extra):
    params = {"engine": engine, QUERY_FIELD.get(engine, "q"): query}
    params.update({k: str(v) for k, v in extra.items()})
    return params


def search(engine, query, api_key, max_attempts=4, **extra):
    params = {"api_key": api_key, **build_params(engine, query, **extra)}
    for attempt in range(1, max_attempts + 1):
        resp = requests.get(ENDPOINT, params=params, timeout=120)
        usage = {k: v for k, v in resp.headers.items() if k.lower().startswith("searchdata-")}
        if resp.ok:
            return resp.json(), usage
        if resp.status_code in FINAL:
            # 401: missing, invalid, or unentitled key. 400: "Parameter '<name>' not allowed." etc.
            raise SystemExit(f"{resp.status_code}: {resp.text[:300]}")
        retry_422 = resp.status_code == 422 and attempt == 1   # target-side failure: one retry only
        if resp.status_code in RETRYABLE or retry_422:
            time.sleep(random.uniform(0, min(2 ** attempt, 30)))   # full jitter
            continue
        raise SystemExit(f"Unexpected {resp.status_code}: {resp.text[:300]}")
    raise SystemExit(f"Gave up after {max_attempts} attempts")


def organic(data):
    """Product pages document organic[]; some docs pages show organic_results[]. Accept both."""
    return data.get("organic") or data.get("organic_results") or []


def main():
    args = [a for a in sys.argv[1:] if a != "--dry-run"]
    if len(args) < 2:
        sys.exit(__doc__)
    engine, query = args[0], args[1]
    extra = dict(a.split("=", 1) for a in args[2:])

    if "--dry-run" in sys.argv:
        prepared = requests.Request(
            "GET", ENDPOINT, params={"api_key": "REDACTED", **build_params(engine, query, **extra)}
        ).prepare()
        print(prepared.url)
        return

    api_key = os.environ.get("WSA_API_KEY")
    if not api_key:
        sys.exit("Set WSA_API_KEY first (dashboard -> SERP API).")

    data, usage = search(engine, query, api_key, **extra)
    print("usage headers:", usage)
    if "search_results" in data:          # DuckDuckGo and Yandex: SERP HTML inside a JSON envelope
        print("search_parameters:", data.get("search_parameters"))
        print("html chars:", len(data["search_results"]))
    else:                                  # Google and Bing: parsed JSON
        for row in organic(data)[:10]:
            print(row.get("rank") or row.get("position"), row.get("title"), row.get("link"))


if __name__ == "__main__":
    main()

Führen Sie python wsa_serp.py google "running shoes" gl=us hl=en device=mobile --dry-run zuerst aus. Es gibt die genaue Anfrage-URL aus, wobei der Schlüssel durch REDACTEDersetzt wird, sodass du die Parameter überprüfen kannst, bevor du eine Suche durchführst.

Node.js (18 oder höher). „URLSearchParams“ übernimmt die Kodierung, und AbortSignal.timeout legt dasselbe 120-Sekunden-Limit fest:

// Build and (optionally) send a SERP API request in Node 18+.
// URLSearchParams handles encoding; the key comes from the environment.
const ENDPOINT = "https://serpapi.webscrapingapi.com/v2";
const QUERY_FIELD = { yandex: "text", google_maps_reviews: "fid", google_reverse_image: "url" };

export function buildSerpUrl(apiKey, engine, query, extra = {}) {
  const url = new URL(ENDPOINT);
  url.searchParams.set("api_key", apiKey);
  url.searchParams.set("engine", engine);
  url.searchParams.set(QUERY_FIELD[engine] ?? "q", query);
  for (const [k, v] of Object.entries(extra)) url.searchParams.set(k, String(v));
  return url;
}

export async function search(engine, query, extra = {}) {
  const apiKey = process.env.WSA_API_KEY;
  if (!apiKey) throw new Error("WSA_API_KEY is required");
  const res = await fetch(buildSerpUrl(apiKey, engine, query, extra), {
    signal: AbortSignal.timeout(120_000),
  });
  if (!res.ok) throw new Error(`SERP API ${res.status}: ${(await res.text()).slice(0, 300)}`);
  const data = await res.json();
  return { data, organic: data.organic ?? data.organic_results ?? [] };
}

// Dry run: show the encoded URL and prove the query survives the round trip.
if (process.argv[1]?.endsWith("build_serp_request.mjs")) {
  const q = 'site:example.com "running shoes" & socks?';
  const u = buildSerpUrl("REDACTED", "google", q, { gl: "us", hl: "en", device: "mobile" });
  console.log(u.toString());
  console.log("round trip ok:", new URL(u).searchParams.get("q") === q);
  const y = buildSerpUrl("REDACTED", "yandex", "pizza", { lr: 213, p: 0 });
  console.log(y.toString());
}

Der Testlauf zeigt, warum die Kodierung wichtig ist. Die Abfrage site:example.com "running shoes" & socks? wird q=site%3Aexample.com+%22running+shoes%22+%26+socks%3F und wird unverändert wieder dekodiert (round trip ok: true). Wenn Sie diese Abfrage manuell in eine URL einfügen, beendet das bloße & beendet Ihren q Wert und leitet einen neuen Parameter namens socks?. Der /v2 Endpunkt validiert Parameter je nach Engine und lehnt Namen ab, die er nicht erkennt, sodass eine manuell erstellte URL auf verwirrende Weise fehlschlägt. Lassen Sie die Bibliothek jedes Mal die Prozent-Kodierung anwenden.

Behandeln Sie den Schlüssel wie ein Passwort. Speichern Sie ihn in serverseitigen Umgebungsvariablen oder einem Secret-Manager und geben Sie ihn niemals im Frontend-Code, in öffentlichen Repositories, in Protokollen oder auf Screenshots preis. Jeder, der den Schlüssel besitzt, kann Ihre Suchanfragen ausführen.

Dokumentation: Zugriff auf die API

Die aktuelle API-Referenz listet elf Suchmaschinen auf: google, google_async, google_maps, google_maps_reviews, google_flights, google_hotels, google_trends, google_reverse_image, bing, duckduckgo, und yandex. Jede verfügt über eigene erforderliche Eingaben und zulässige Parameter. Betrachten Sie nur diese als unterstützt, auch wenn ältere Dokumentationsseiten andere Google-Suchmaschinen beschreiben.

Drei Suchmaschinen beziehen ihre Haupteingabe nicht aus q. Yandex nimmt die Suchanfrage in text, „Google Maps Reviews“ die fidund Google Reverse Image ein Bild url. Die oben genannten Python- und Node-Clients ordnen diese Felder bereits für Sie zu. Google Maps und Google Hotels benötigen außerdem type=search oder type=place, wodurch sich das andere Pflichtfeld ändert.

„Google-Tarife“ bezieht sich auf die veröffentlichten monatlichen Google-Tarife, die im Abschnitt „Preise“ behandelt werden. Die Preise für Bing, DuckDuckGo und Yandex werden auf Anfrage mitgeteilt.

Möglicherweise findest du Dokumentationsseiten für andere Google-Dienste wie Autocomplete, Events, Finance, Jobs, Local Services, Maps Photos, Play, Product und Scholar. Diese sind jedoch nicht in der Liste der unterstützten Dienste enthalten; baue daher keine Pipeline darauf auf.

Dokumentation: Referenz zu SearchData- und SERP-APIs

Legen Sie gl auf den zweistelligen Ländercode, hl auf die Sprache der Benutzeroberfläche und device auf desktop, mobileoder tablet. Fügen Sie domain für einen bestimmten Google-Host und uule für einen kodierten Standort, wenn der Kontext auf Stadtebene eine Rolle spielt. Speichere diese Werte zusammen mit jedem Ergebnis, da dieselbe Suchanfrage in jedem Markt unterschiedlich gerankt werden kann.

Google selbst gibt an, dass die Ergebnisse davon abhängen, von wo aus gesucht wird; daher ist ein Ranking ohne Angabe des Marktes nur eine halbe Wahrheit. Diese kanadische, englischsprachige Desktop-Suche nach „history“ auf google.ca wird über den Python-Client aus dem Abschnitt „Erste Anfrage“ ausgeführt:

python wsa_serp.py google history gl=ca hl=en domain=google.ca device=desktop

Wenn Sie eine bestimmte Stadt benötigen, wie beispielsweise London, Ontario, fügen Sie deren uule Wert als ein weiteres uule=... Argument hinzu. Verwende nur die Parameter, die in der Dokumentation deiner Suchmaschine aufgeführt sind. Ältere Beispiele, die nach Datum sortieren oder nach Zeiträumen filtern, gelten nicht für /v2 Google-Suche nicht, und der Endpunkt lehnt Parameter ab, die er nicht zulässt.

Auch der Ergebnistyp und die Paginierung beeinflussen die Rückgabe:

• „Surfaces“: tbm wechselt den Ergebnistyp: isch für Bilder, vid für Videos, nws für Nachrichten und shop für Shopping. Für Google Jobs-Ergebnisse verwenden Sie ibp=htl;jobs.
• Paginierung: start Legt fest, wie viele Ergebnisse übersprungen werden sollen, und num legt fest, wie viele Ergebnisse pro Seite angezeigt werden sollen.

Am nützlichsten ist hier eine systematische Vorgehensweise. Bevor Sie Daten erfassen, wählen Sie ein kleines, festes Raster aus Suchanfrage × Land × Sprache × Gerät und ändern Sie dieses zwischen den Durchläufen nicht. Wenn ein Durchlauf in einer Woche gl=us&device=mobile und der nächste gl=us&device=desktopverwendet, kann ein „Rangrückgang“ lediglich auf einen Gerätewechsel zurückzuführen sein. Jede Antwort ist eine Beobachtung eines einzelnen Marktes und keine allgemeingültige Wahrheit; daher sind Vergleiche nur innerhalb derselben Rasterzelle aussagekräftig.

Die vollständige Liste der Anfragefelder und Antwortblöcke finden Sie auf der Seite „Steuerelemente“ der Google-Such-API.

Dokumentation: Parameter der Google-Such-API

Lesen Sie das „organic“-Array für die gerangierten Ergebnisse aus, die jeweils einen Titel, einen Link, einen Anzeigelink, eine Beschreibung und einen Rang enthalten. Behandeln Sie alle anderen Module, wie z. B. verwandte Suchanfragen, Navigation, Anzeigen oder lokale Ergebnisse, als optional. Speichern Sie jede Zeile zusammen mit der Suchanfrage, dem Markt, dem Gerät und dem Erfassungszeitpunkt, damit spätere Rangvergleiche aussagekräftig bleiben.

Eine Google-Antwort enthält einige Blöcke auf oberster Ebene. general beschreibt die Anfrage (Suchmaschine, Sprache, Standort, Mobil-Flag und Suchtyp), input enthält die ursprüngliche Such-URL, navigation[] listet weitere Google-Anzeigeflächen für die Suchanfrage auf und organic[] enthält die gerangierten Ergebnisse. Eine Bing-Antwort enthält general, organic[]und related[].

Alles andere ist bedingt. Anzeigen, lokale Ergebnisse, Shopping, Medien und verwandte Suchanfragen erscheinen nur, wenn die Ergebnisseite sie anzeigt, und welche SERP-Funktionen Google anzeigt, ändert sich je nach Suchanfrage, Standort und Gerät. Unterscheiden Sie daher in Ihrem Code zwischen zwei Fällen: einer fehlgeschlagenen Anfrage (einem HTTP-Fehler) und einer erfolgreichen Anfrage, bei der ein Modul fehlt. Letzteres ist eine normale Beobachtung, kein Fehler.

Schreiben Sie den Parser defensiv. Einige Dokumentationsseiten zeigen die Rangliste wie folgt an organic_results[] mit position anstelle von organic[] mit rank, lesen Sie also eine der beiden. Dieses Skript wandelt eine Antwort in Rangzeilen um. Die Eingabedatei ist ein beschriftetes Beispiel, keine Live-Ausgabe:

"""Flatten a Google or Bing SERP API response into rank rows.

Organic results may arrive as organic[] (product pages) or organic_results[] (some docs pages),
and modules such as related[] or navigation[] are optional, so read them defensively.
"""
import json
import sys
from datetime import datetime, timezone


def rank_rows(data, query, market):
    rows = []
    captured = datetime.now(timezone.utc).isoformat(timespec="seconds")
    for item in data.get("organic") or data.get("organic_results") or []:
        rows.append({
            "captured_at": captured,
            "engine": data.get("general", {}).get("search_engine"),
            "query": query,
            "market": market,
            "rank": item.get("rank") or item.get("position"),
            "title": item.get("title"),
            "link": item.get("link"),
        })
    return rows


if __name__ == "__main__":
    data = json.load(open(sys.argv[1] if len(sys.argv) > 1 else "sample_google.json"))
    for row in rank_rows(data, "running shoes", "us/en/mobile"):
        print(row)
    print("optional modules present:", [k for k in ("navigation", "related", "related_questions") if k in data])

Anhand der Beispieldatei gibt es pro organischem Ergebnis eine Zeile aus und listet auf, welche optionalen Module vorhanden waren:

{'captured_at': '2026-10-29T12:03:56+00:00', 'engine': 'google', 'query': 'running shoes', 'market': 'us/en/mobile', 'rank': 1, 'title': 'Example result one', 'link': 'https://example.com/a'}
{'captured_at': '2026-10-29T12:03:56+00:00', 'engine': 'google', 'query': 'running shoes', 'market': 'us/en/mobile', 'rank': 2, 'title': 'Example result two', 'link': 'https://example.org/b'}
optional modules present: ['navigation']

Eine Rangzeile sollte mindestens captured_at: Suchmaschine, Suchanfrage, Markt, Gerät, Rang, Titel und Link enthalten. Mit diesen Feldern können Sie Durchläufe vergleichen, Bewegungen grafisch darstellen und bei Einbußen Warnmeldungen auslösen. Das ist der Kern der Überwachung von Rankings und SERP-Funktionen im Zeitverlauf. Falls Ihre gespeicherten Links Google-Weiterleitungs-Wrapper enthalten, informieren Sie sich über Google-„/goto“-Weiterleitungslinks in Ergebnis-URLs, bevor Sie nach URLs deduplizieren.

Legen Sie engine=bing und übergeben Sie die Suchanfrage in q. Steuern Sie den Markt mit mkt, wie zum Beispiel en-USsowie cc für das Land und lang für die Sprache. Fügen Sie locationoder lat und lon, um eine genaue Herkunft anzugeben, safesearch zum Filtern sowie first mit count zum Blättern durch die Ergebnisse. Die Bing-Antworten werden als geparstes JSON zurückgegeben.

Die curl-Version für den US-Markt, erste Seite mit 10 Ergebnissen:

curl --get --fail-with-body --max-time 120 "https://serpapi.webscrapingapi.com/v2" \
  --data-urlencode "api_key=$WSA_API_KEY" \
  --data-urlencode "engine=bing" \
  --data-urlencode "q=coffee roasters" \
  --data-urlencode "mkt=en-US" --data-urlencode "cc=us" --data-urlencode "lang=en" \
  --data-urlencode "first=0" --data-urlencode "count=10"

Mit dem Python-Client aus dem Abschnitt „Erste Anfrage“ lässt sich derselbe Aufruf in einer Zeile ausführen:

python wsa_serp.py bing "coffee roasters" mkt=en-US cc=us lang=en first=0 count=10

Bing gibt general, organic[]und related[]. Anzeigen und Bilder sind optionale Module, daher gelten dieselben Vorsichtsmaßnahmen: Lesen Sie organic[], behandle alles andere als vorhanden oder nicht vorhanden und speichere jede Zeile mit ihrem Markt. safesearch nimmt off, moderateoder strict.

Behalte mkt, cc, und lang über alle Durchläufe hinweg konsistent, genau wie bei Googles gl und hl. Die Preise für Bing werden auf Anfrage festgelegt, und die Testversion mit 100 Suchanfragen deckt Google ab. Anforderungsfelder und Antwortblöcke finden Sie auf der Seite zur Bing-Such-API.

Dokumentation: Grundlegende Bing-API-Anfragen

Beide Suchmaschinen geben JSON zurück, wobei search_parameters, das die Anfrage beschreibt, sowie search_results, einer Zeichenkette, die den Quellcode der SERP-HTML enthält. WebScrapingAPI wertet dieses HTML nicht aus, sodass Ihre Anwendung die benötigten Felder selbst extrahiert. Verknüpfen Sie Ihre Selektoren mit einer tatsächlichen Erfassung, versionenieren Sie sie, speichern Sie den Rohdatensatz und geben Sie eine Warnung aus, wenn ein Selektor nicht mehr passt.

DuckDuckGo-Anfragefelder: q für die Abfrage, kl für Region und Sprache (z. B. en_US), kad für die Sprache der Benutzeroberfläche, kp für die sichere Suche (1 ein, -1 „moderat“, -2 aus), df für die Zeit (d, w, m, y) sowie device.

Yandex-Anfragefelder: text für die Abfrage, lr für die Regions-ID (zum Beispiel 213), lang, device, yandex_domain, p für die Seite (nullbasiert, d. h. p=0 ist die erste Seite) sowie within für die Zeit (77 für die letzten 24 Stunden, 1 für die letzten zwei Wochen).

# DuckDuckGo, SERP HTML in a JSON envelope
curl --get --fail-with-body --max-time 120 "https://serpapi.webscrapingapi.com/v2" \
  --data-urlencode "api_key=$WSA_API_KEY" \
  --data-urlencode "engine=duckduckgo" \
  --data-urlencode "q=privacy research" \
  --data-urlencode "kl=en_US" --data-urlencode "df=w"

# Yandex, SERP HTML in a JSON envelope (query parameter: text)
curl --get --fail-with-body --max-time 120 "https://serpapi.webscrapingapi.com/v2" \
  --data-urlencode "api_key=$WSA_API_KEY" \
  --data-urlencode "engine=yandex" \
  --data-urlencode "text=pizza" \
  --data-urlencode "lr=213" --data-urlencode "p=0"

Das Extraktionsmuster ist für beide Engines identisch: den Header validieren, das HTML parsen, Ergebnislinks auswählen, die engine-eigenen Navigationslinks entfernen, jede Zeile mit einer Selektor-Version kennzeichnen, bei fehlender Übereinstimmung deutlich einen Fehler melden und das Roh-HTML beibehalten, damit man es später erneut verarbeiten kann. Dieses Skript verwendet Beautiful Soup mit CSS-Selektoren:

"""Pull result links out of a DuckDuckGo or Yandex SERP API envelope.

These engines return {"search_parameters": {...}, "search_results": "<html>...</html>"}.
Your application owns extraction: pin the selector after inspecting a real capture,
version it, and alert when it stops matching. The selectors below fit the synthetic
fixtures only.
"""
import json
import sys
from urllib.parse import urlparse

from bs4 import BeautifulSoup

SELECTORS = {"duckduckgo": "div.result a.result-link", "yandex": "li.serp-item a.link"}
ENGINE_HOSTS = ("duckduckgo.com", "yandex.com", "yandex.ru")


def extract(envelope, selector_version="fixture-v1"):
    params = envelope.get("search_parameters", {})
    engine = params.get("search_engine")
    html = envelope.get("search_results")
    if not isinstance(html, str) or "<html" not in html.lower():
        raise ValueError("search_results is missing or is not HTML; store the raw envelope and alert")
    soup = BeautifulSoup(html, "html.parser")
    rows = []
    for pos, a in enumerate(soup.select(SELECTORS[engine]), start=1):
        host = urlparse(a.get("href", "")).hostname or ""
        if host.endswith(ENGINE_HOSTS):
            continue  # skip the engine's own navigation links
        rows.append({"engine": engine, "query": params.get("query"), "position": pos,
                     "title": a.get_text(strip=True), "link": a["href"],
                     "selector_version": selector_version})
    if not rows:
        raise ValueError(f"selector matched nothing for {engine}; markup may have changed")
    return rows


if __name__ == "__main__":
    for path in sys.argv[1:] or ["sample_ddg_envelope.json", "sample_yandex_envelope.json"]:
        for row in extract(json.load(open(path))):
            print(row)

Die Selektoren in SELECTORS passen nur zu den synthetischen Beispieldateien. Das tatsächliche Markup von DuckDuckGo und Yandex ist anders und ändert sich. Bevor du dies in der Produktion ausführst, speichere einen echten Envelope, untersuche dessen HTML, lege deine eigenen Selektoren fest und passe selector_version , sobald du sie änderst. Wenn sich das Markup ändert, löst das ValueError wird ausgelöst, anstatt dass Ihre Pipeline stillschweigend null Ergebnisse speichert, und da Sie den Roh-HTML-Code beibehalten haben, können Sie die betroffenen Durchläufe erneut extrahieren, sobald die Selektoren korrigiert sind.

Suchmaschinenspezifische Felder findest du auf den Seiten zur DuckDuckGo-Such-API und zur Yandex-Such-API.

Dokumentation: DuckDuckGo-API-Parameter · Yandex-API-Parameter

Verwenden Sie die spezialisierten Google-Suchmaschinen, wenn die Antwort außerhalb der regulären Web-Ergebnisse zu finden ist. Google Maps findet Orte, „Maps Reviews“ liest die Bewertungen eines Ortes aus fid, „Trends“ liefert Widgets zum Interesse im Zeitverlauf, „Hotels“ und „Flights“ liefern Reiseergebnisse und „Reverse Image“ findet Übereinstimmungen zu einem Bild anhand der URL. Jede Suchmaschine hat ihre eigenen erforderlichen Eingaben und Parameter.

Sie alle verwenden denselben Endpunkt, denselben Schlüssel und dieselben Kodierungsregeln wie die Standardsuche. Nur der engine Wert und die Felder ändern sich:

• google_maps: Senden type=search mit qoder type=place mit data. ll=@lat,lon,zoom legt die Kartenansicht fest, und place_type schränkt die Suche auf Hotels oder Ferienwohnungen ein. Eine Paginierung ist nicht dokumentiert.
• google_maps_reviews: Senden Sie den fid, das Sie aus dem knowledge.fid Feld einer Google-Suchergebnisantwort entnehmen. Sortieren mit sort (qualityScore, newestFirst, ratingHigh, ratingLow) und paginieren mit start und num.
• google_trends: Sende q mit geo, date (today 12-m, now 1-Hoder einem YYYY-MM-DD YYYY-MM-DD Bereich), cat, und gprop (images, news, froogle, youtube). Die Antwort enthält widgets[], wie z. B. TIMESERIES und GEO_MAP.
• google_hotels: senden type=search mit qoder type=place mit pid, sowie check_in_date und check_out_date. Filter für Belegung, Währung und kostenlose Stornierung sind optional.
• google_flights: q ist ein kodiertes Google-Flights-Abfragetoken, kein Klartext. Fügen Sie curr, hlsowie gl für Währung und Markt.
• google_reverse_image: Senden Sie die urlund verwende lens (products, visual_matches, exact_matches, homework), um den Übereinstimmungstyp auszuwählen.

Wenn Sie sich zwischen der umgekehrten Bildersuche und tbm=isch Bildergebnissen, lesen Sie den Vergleich der Google-Bildersuch-APIs.

Dokumentation: Google-Suchmaschinen

Senden Sie die Suche mit engine=google_async. Die API stellt sie in die Warteschlange und gibt response_id sofort zurück. Speichern Sie diese ID zusammen mit Ihrem Job und fragen Sie anschließend denselben /v2 Endpunkt abfragen, wobei snapshot_id auf die ID und type=serp alle 10 bis 30 Sekunden abfragen, bis die fertige SERP-Nutzlast eintrifft. Begrenzen Sie die Gesamtwartezeit.

Async eignet sich für große Stapel und Worker, die eine Anfrage nicht 120 Sekunden lang offen halten können. Es akzeptiert die regulären Google-Felder sowie device sowie response=json. Es ist ausschließlich für Google gedacht: Bing, DuckDuckGo und Yandex verfügen nicht über eine asynchrone Engine, daher sollten Sie keine gemeinsame asynchrone Warteschlange für diese Suchmaschinen entwerfen.

"""Submit a google_async job, then poll for the finished SERP payload.

Usage:
  export WSA_API_KEY=...
  python google_async.py "events in new york city"
  python google_async.py "events in new york city" --dry-run
"""
import os
import random
import sys
import time

import requests

ENDPOINT = "https://serpapi.webscrapingapi.com/v2"


def submit(api_key, query, **extra):
    r = requests.get(ENDPOINT, params={"api_key": api_key, "engine": "google_async", "q": query, **extra}, timeout=60)
    r.raise_for_status()
    return r.json()["response_id"]          # store this id with your job record


def poll(api_key, response_id, max_wait=600):
    deadline = time.monotonic() + max_wait
    while time.monotonic() < deadline:
        r = requests.get(ENDPOINT, params={"api_key": api_key, "snapshot_id": response_id, "type": "serp"}, timeout=60)
        if r.ok:
            body = r.json()
            if body.get("status") in (None, "finished"):
                return body                  # persist it; don't re-poll old ids later
        elif r.status_code not in (429, 500, 502, 503):
            raise SystemExit(f"{r.status_code}: {r.text[:300]}")
        time.sleep(random.uniform(10, 30))   # docs: poll every 10 to 30 seconds
    raise SystemExit(f"No result for {response_id} after {max_wait} s")


if __name__ == "__main__":
    query = sys.argv[1] if len(sys.argv) > 1 else "events in new york city"
    if "--dry-run" in sys.argv:
        for p in ({"api_key": "REDACTED", "engine": "google_async", "q": query},
                  {"api_key": "REDACTED", "snapshot_id": "<response_id>", "type": "serp"}):
            print(requests.Request("GET", ENDPOINT, params=p).prepare().url)
        sys.exit(0)
    key = os.environ.get("WSA_API_KEY") or sys.exit("Set WSA_API_KEY first.")
    rid = submit(key, query)
    print("response_id:", rid)
    print(str(poll(key, rid))[:500])

Speichere jedes fertige Ergebnis sofort nach seinem Eintreffen und greife später nicht erneut auf alte IDs zurück. Die Schleife hat eine feste Frist und behandelt jeden unerwarteten Status als Stopp, sodass ein festgefahrener Job einen Worker nicht auf unbestimmte Zeit blockieren kann.

Dokumentation: Asynchrone APIs

Versuche es bei 401- oder Validierungsfehlern nicht erneut. Korrigiere den Schlüssel, den Plan oder die Parameter. Versuchen Sie es bei den Fehlern 429, 500, 502 und 503 einige Male mit exponentiellem Backoff und Jitter erneut und verlangsamen Sie den Versuch bei 429. Ein 422 bedeutet, dass die Suchmaschine einen Fehler, ein Timeout oder eine Challenge zurückgegeben hat; versuchen Sie es daher nur einmal erneut, wenn der Fehler vorübergehend zu sein scheint.

Authentifizierungsfehler sind leicht zu erkennen. Eine Anfrage ohne Schlüssel führt zu einem 401-Fehler mit der Meldung „Zugriff verweigert. Es wurde kein Schlüssel api_key angegeben.“ zurück, und ein falscher oder nicht berechtigter Schlüssel führt zu einem 401-Fehler mit Authentication failure: Invalid API key…. Ein erneuter Versuch führt in beiden Fällen lediglich zu einer Wiederholung des Fehlers.

Validierungsmeldungen benennen das Problem direkt: Parameter '<name>' not allowed., Parameter '<name>' is required., Parameter '<name>' must be in range …und Parameter '<a>' cannot be used with parameter '<b>'. Deshalb schlagen Parameter, die aus alten Beispielen kopiert wurden, bei /v2: Jede Engine akzeptiert nur ihre eigenen, dokumentierten Felder.

Ein 429 „Too Many Requests“ bedeutet, dass Sie zu viele Anfragen auf einmal senden. Verringern Sie die Parallelität und warten Sie eine Weile, bevor Sie es erneut versuchen. Bei den Fehlern 500, 502 und 503 reichen einige Wiederholungsversuche mit exponentiellem Backoff und vollem Jitter aus, und die zufälligen Verzögerungen verhindern, dass eine ganze Flotte von Workern im Gleichschritt neue Versuche unternimmt. Die search() Funktion im Python-Client setzt diese gesamte Richtlinie um: Sie bricht bei einem 401 ab, wiederholt die wiederholbaren Codes mit verzögerten Wartezeiten, versucht es bei einem 422 einmal erneut und gibt nach vier Versuchen auf.

Protokollieren Sie bei jedem Aufruf zwei Antwort-Header zur Kostenverfolgung: Searchdata-Call-Credit-Usage (durch diesen Aufruf verbrauchte Credits) und Searchdata-Current-Credit-Usage (aktueller Kontostand). Der Client gibt sie als usage. Protokolliere den Status, die Header und den Anfragekontext, aber niemals den Schlüssel.

Unterscheiden Sie in Ihren Metriken zwischen HTTP-Fehlern und leeren Modulen. Eine 200-Antwort ohne related[] Block ist eine erfolgreiche Suche und sollte keinen erneuten Versuch auslösen.

Dokumentation: Fehler und Header

Die Google-Tarife richten sich nach der Anzahl der monatlichen Suchanfragen: „Starter“ kostet 28 $ für 10.000, „Grow“ 130 $ für 50.000, „Business“ 550 $ für 250.000 und „Pro“ 1.600 $ für 1.000.000. Die Testversion umfasst 100 Google-Suchanfragen für 0 $. Die Preise für Bing, DuckDuckGo und Yandex richten sich ab Oktober 2026 nach einem Angebot für Ihr Arbeitsvolumen.

Die Preise sind in USD angegeben (Stand: Oktober 2026). Jeder Tarif, einschließlich der Testversion, umfasst Google-Produktdaten, globale Standorte, SERP-Analyse, Massenverarbeitung, alle Geräte, JSON-, CSV- und HTML-Ausgabe sowie die Bildersuche. Die Tarife unterscheiden sich hinsichtlich des monatlichen Suchkontingents.

Um die Größe eines Tarifs zu ermitteln, multiplizieren Sie die einzelnen Komponenten Ihres Marktrasters:

Monatliche Suchanfragen = Keywords × Märkte × Geräte × Ergebnistypen × Aktualisierungsläufe pro Monat

Rechnen Sie dann noch Spielraum für Tests und für Keywords hinzu, die Sie später hinzufügen werden. Beispiel: 500 Keywords × 2 Länder × 2 Geräte × 4 wöchentliche Durchläufe = 8.000 Suchanfragen pro Monat, was problemlos in den „Starter“-Tarif passt. Wenn Sie dasselbe Projekt auf tägliche Durchläufe umstellen, ergibt dies etwa 60.000 Suchanfragen, wodurch Sie in den „Business“-Tarif wechseln. Die Aktualisierungshäufigkeit multipliziert alle anderen Werte; legen Sie sie daher danach fest, wie oft die von den Daten abhängigen Entscheidungen tatsächlich getroffen werden.

Nutzen Sie die Testphase, um Ihre repräsentativen Suchanfragen, Märkte, Geräte und Ausgabefelder zu validieren, bevor Sie sich auf ein Volumen festlegen. Wenn Sie auch andere Anbieter in Betracht ziehen, vergleichen Sie die Preise für SERP-APIs verschiedener Anbieter.

Die SERP-API liefert Suchergebnisseiten zurück, nicht die Seiten hinter den einzelnen Links, und sie definiert keinen universellen Rang. Die Extraktion von DuckDuckGo und Yandex ist Aufgabe Ihres Codes, „async“ ist nur für Google verfügbar, und die Antworten im Google-KI-Modus sind ein separates Produkt. Verwenden Sie die Scraper-API, die Data-API oder einen verwalteten Feed, wenn diese Einschränkungen eine Rolle spielen.

• Die API endet bei der Ergebnisseite. Um die Seiten hinter den Links abzurufen, verwenden Sie die Scraper-API. Erfahren Sie, wie Sie die Scraper-API nutzen.
• Der AI-Modus ist separat. Für Antworten, Zitate und Markenerwähnungen im Google AI-Modus verwenden Sie die Google AI-Modus-Daten aus der Data-API.
• Es handelt sich um eine Abfrage zum Zeitpunkt der Anfrage, nicht um einen Feed. Wenn du regelmäßig nach einem festgelegten Zeitplan bereitgestellte, kontrollierte Datensätze benötigst, anstatt selbst Abfragen durchzuführen, informiere dich über Daten-Feeds für Suchergebnisse.
• Es werden nur die aufgeführten Suchmaschinen unterstützt. Stützen Sie sich auf die elf Suchmaschinen in der Referenz, nicht auf ältere Dokumentationsseiten.
• HTML-Suchmaschinen erfordern Pflege. Die Selektoren für DuckDuckGo und Yandex müssen Sie selbst pflegen, wenn sich deren Markup ändert.
• Asynchronität ist nur bei Google möglich. Planen Sie für Bing, DuckDuckGo und Yandex synchrone Worker ein.
• Ein Ergebnis entspricht einer Beobachtung. Ein Rang beschreibt eine Suchanfrage, einen Markt, ein Gerät und einen Zeitpunkt. Ob das Fehlen eines Ergebnisses wirtschaftlich von Bedeutung ist, entscheiden Sie, nicht die API.
• Die Nutzung unterliegt bestimmten Regeln. Sammeln Sie zulässige öffentliche Ergebnisse gemäß der Nutzungsvereinbarung der WebScrapingAPI und den für Sie geltenden Anforderungen.

Eine SERP-API ist ein Webdienst, der eine Suche für Sie durchführt und die Suchergebnisseite als Daten zurückgibt. Sie senden eine Suchanfrage, eine Suchmaschine sowie Kontextdaten wie Land, Sprache und Gerät. Die SERP-API von WebScrapingAPI gibt für Google und Bing geparstes JSON und für DuckDuckGo und Yandex HTML in einem JSON-Envelope zurück.

Speichern Sie Ihren API-Schlüssel in einer Umgebungsvariablen und senden Sie anschließend eine GET-Anfrage an https://serpapi.webscrapingapi.com/v2 mit dem API-Schlüssel, der Suchmaschine und Ihrer Suchanfrage. Fügen Sie Markensteuerungen wie „gl“ und „hl“ für Google hinzu, lesen Sie die organischen Ergebnisse aus der JSON-Antwort aus und speichern Sie jede Zeile mit ihrer Suchanfrage, dem Markt, dem Gerät und dem Erfassungszeitpunkt.

Registrieren Sie ein WebScrapingAPI-Konto und abonnieren Sie anschließend die SERP-API über das Dashboard, um Ihren Schlüssel zu erhalten. Die Testversion umfasst 100 Google-Suchen. Speichern Sie den Schlüssel in einer Umgebungsvariablen oder einem Secrets-Manager auf Ihrem Server und geben Sie ihn niemals im Browser-Code, in öffentlichen Repositories, in Logs oder auf Screenshots preis.

Ja. Die Testversion der SERP-API kostet 0 $ und umfasst 100 Google-Suchen – genug, um Ihre Keywords, Märkte, Geräte und die Ausgabe zu testen, bevor Sie sich für einen Tarif entscheiden. Kostenpflichtige Google-Tarife beginnen bei 28 $ pro Monat für 10.000 Suchanfragen. Die Preise für Bing, DuckDuckGo und Yandex werden auf Basis eines Angebots für Ihr spezifisches Arbeitsvolumen festgelegt.

Beim SERP-Scraping werden die Ergebnisse erfasst, die eine Suchmaschine für eine Suchanfrage anzeigt, wie z. B. Titel, Links, Positionen und Funktionen wie verwandte Suchanfragen. Wenn Sie dies selbst durchführen, müssen Sie sich mit Blöcken und Layoutänderungen auseinandersetzen. Eine SERP-API überträgt diese Arbeit an den Anbieter, sodass Ihr Code eine Anfrage sendet und die Ergebnisse als Daten erhält.

Ja. Installieren Sie „Requests“, lesen Sie Ihren Schlüssel aus einer Umgebungsvariablen aus und übergeben Sie „api_key“, „engine“ und „q“ im Argument „params“, damit „Requests“ diese Werte kodiert. Legen Sie ein Timeout von etwa 120 Sekunden fest, wiederholen Sie Versuche bei 429- und 5xx-Antworten mit Backoff und lesen Sie die organische Liste aus der JSON-Antwort für Google oder Bing aus.

Sie unterstützt Google, Bing, DuckDuckGo und Yandex. Google verfügt zudem über spezielle Suchmaschinen für asynchrone Suche, Maps, Maps-Bewertungen, Hotels, Flüge, Trends und die Bildersuche. Google und Bing geben geparstes JSON zurück. DuckDuckGo und Yandex geben den HTML-Code der Ergebnisseite in einem JSON-Umschlag zurück, den Ihre Anwendung parst.

Keine Seite der SERP-API verspricht dies. WebScrapingAPI betreibt die Suchzugriffsinfrastruktur hinter jeder Anfrage, und wenn eine Suchmaschine eine Challenge-Seite, einen Fehlerstatus oder ein Timeout zurückgibt, antwortet die API mit einem 422-Website-Fehler, anstatt fehlerhafte Daten weiterzuleiten. Versuchen Sie es einmal erneut, wenn der Fehler vorübergehend zu sein scheint, und protokollieren Sie ihn anschließend.

Bei diesen beiden Suchmaschinen gibt die SERP-API die Quell-Ergebnisseite als HTML innerhalb eines JSON-Containers zurück, anstatt parste Sammlungen bereitzustellen. Ihre Anwendung entscheidet, was extrahiert werden soll. Untersuchen Sie eine echte Antwort, ordnen Sie ihr CSS-Selektoren zu, versionieren Sie diese, bewahren Sie das Roh-HTML auf und geben Sie eine Warnung aus, wenn ein Selektor nach einer Layoutänderung nicht mehr passt.

Wählen Sie einen festen Satz von Keywords, Ländern, Sprachen und Geräten aus und fragen Sie diese nach einem festgelegten Zeitplan ab. Speichern Sie Rang, Titel und Link jedes organischen Ergebnisses zusammen mit dem Erfassungszeitpunkt und dem Markt. Vergleichen Sie die Ergebnisse nur innerhalb desselben Marktes und desselben Geräts und behandeln Sie fehlende SERP-Funktionen als Beobachtung, nicht als Fehler.

Die SERP-API liefert Google- und Bing-Ergebnisse als geparstes JSON sowie DuckDuckGo- und Yandex-Ergebnisseiten als HTML in einem JSON-Container, wobei bei jeder Anfrage Markt, Sprache und Gerät festgelegt werden können. Wenn Sie Ihre Keywords, Märkte und Ihren Aktualisierungszeitplan kennen, vergleichen Sie die SERP-API-Tarife und wählen Sie das für Sie passende Kontingent aus.