Jedes ScrapeUnblocker-Plugin Aus Python, Node.js, PHP oder Ruby Aufrufen

Plugins sind der schnellste Weg zu strukturierten Daten von einer bestimmten Website. Du schickst ein Suchwort oder eine ID und bekommst sauberes JSON zurück, ohne Selektoren pflegen zu müssen. Die Frage war immer nur, wie viel Klebecode zwischen deinem Projekt und diesem JSON liegt.

Ab SDK 0.11.0 sehr wenig. Die Clients für Python, Node.js, PHP und Ruby haben eine Methode für jedes öffentliche Plugin, dazu einen generischen Aufruf für jeden Plugin-Endpunkt. Dieser Guide zeigt, wie die Methoden funktionieren, geht ein kleines Skript über mehrere Händler durch und behandelt das, was zählt, sobald es nach Zeitplan läuft: Nebenläufigkeit und Fehlerbehandlung.

Was Sich Geändert Hat

Drei Dinge kamen gleichzeitig:

• Eine Methode für jedes Plugin in allen vier SDKs. Die Plugin-Übersicht listet jetzt mehr als 60 Plugins in 14 Kategorien: E-Commerce, Lebensmittel, Reisen, Google, weitere Suchmaschinen, Immobilien, Fahrzeuge, Jobs, Bewertungen, lokale Unternehmen, Apps, Video und Musik sowie SEO und Werbung. Jedes davon hat eine passende Methode.
• Eine Dokumentationsseite pro Plugin. Jede Seite listet die Felder, zeigt eine Beispielantwort und enthält den Aufruf in cURL, Python, Node.js, PHP und Ruby nebeneinander.
• Plugins im MCP-Server. Der MCP-Server und der gehostete Connector haben zwei neue Tools, list_plugins und run_plugin, damit ein KI-Assistent dieselben Plugins finden und ausführen kann.

Das SDK Installieren

Wähle deine Sprache:

pip install scrapeunblocker              # Python 3.8+
npm install scrapeunblocker              # Node.js 18+
composer require scrapeunblocker/client  # PHP 8.1+
gem install scrapeunblocker              # Ruby 2.7+

Lege danach deinen API-Key in einer Umgebungsvariable ab. Alle vier Clients lesen ihn automatisch:

export SCRAPEUNBLOCKER_KEY="YOUR_API_KEY"

Den Key bekommst du im Dashboard. Wenn du schon ein SDK installiert hast, aktualisiere auf 0.11.0 oder neuer, um alle Plugin-Methoden zu bekommen.

So Funktionieren die Plugin-Methoden

Das Muster ist in jeder Sprache gleich. Wenn du ein Plugin benutzt hast, kannst du alle benutzen:

• Die Methode heißt wie das Plugin. Walmart Search ist walmart_search in Python und Ruby und walmartSearch in Node.js und PHP.
• Die Haupteingabe kommt zuerst. Ein Suchwort, eine Produkt-ID oder eine Domain ist das erste Argument.
• Alles andere ist eine Option. Keyword-Argumente in Python und Ruby, ein Options-Objekt in Node.js (Schlüssel in camelCase), ein Array mit den Parameternamen der API in PHP.
• Weggelassene Optionen werden nicht gesendet. Es gelten die Standardwerte der API, du übergibst also nur, was du ändern willst.
• Listen erledigt das SDK. Wo ein Plugin mehrere Werte annimmt, übergibst du eine Liste, und das SDK sendet sie kommagetrennt.

Hier ist dieselbe Best-Buy-Suche in allen vier Sprachen:

# Python
result = su.bestbuy_search("laptop", sort="price_low", max_results=48)

// Node.js
const result = await su.bestbuySearch("laptop", { sort: "price_low", maxResults: 48 });

// PHP
$result = $su->bestbuySearch('laptop', ['sort' => 'price_low', 'max_results' => 48]);

# Ruby
result = su.bestbuy_search("laptop", sort: "price_low", max_results: 48)

In jedem Fall ist su der Client: Client() in Python, new ScrapeUnblockerClient() in Node.js, new Client() in PHP und ScrapeUnblocker::Client.new in Ruby.

Beispiel: Preise bei Drei Händlern Vergleichen

Ein gutes erstes Projekt ist ein Preisvergleich über mehrere Shops. Walmart, Target und Best Buy haben jeweils ein Such-Plugin, und alle drei akzeptieren dieselben Optionen sort="price_low" und max_results. Ihre Antworten sind aber nicht identisch. Jedes Plugin liefert die Felder, die die Website selbst verwendet:

• Walmart nennt den Produktnamen name, die ID id und den alten Preis wasPrice.
• Target verwendet title und die eigene Produkt-ID tcin.
• Best Buy verwendet title, sku und originalPrice und liefert zusätzlich eine model-Nummer.

Ein Feld ohne Wert fehlt bei diesem Produkt komplett. Die erste Aufgabe ist also, die drei Formate auf eines abzubilden:

from scrapeunblocker import Client

su = Client()  # reads SCRAPEUNBLOCKER_KEY
QUERY = "wireless headphones"

def normalize(store, item):
    return {
        "store": store,
        "id": item.get("id") or item.get("tcin") or item.get("sku"),
        "title": item.get("name") or item.get("title"),
        "brand": item.get("brand") or "",
        "price": item.get("price"),
        "regular_price": item.get("wasPrice") or item.get("originalPrice"),
        "url": item.get("url"),
    }

stores = {
    "walmart": su.walmart_search,
    "target": su.target_search,
    "bestbuy": su.bestbuy_search,
}

rows = []
for store, search in stores.items():
    result = search(QUERY, sort="price_low", max_results=48)
    rows += [normalize(store, p) for p in result.get("products", [])]

sony = [r for r in rows if r["brand"].lower() == "sony" and r["price"]]
for r in sorted(sony, key=lambda r: r["price"])[:10]:
    print(f'{r["store"]:8} {r["price"]:>8.2f}  {r["title"][:60]}')

Drei Aufrufe, eine Tabelle, jede Zeile mit Shop, Preis und Link. Wenn du die Zeilen einmal am Tag in eine Datenbank schreibst, hast du eine Preishistorie.

Ein ehrlicher Hinweis: Schwierig ist nicht das Scraping, sondern dasselbe Produkt über mehrere Shops hinweg zuzuordnen. Die Titel unterscheiden sich von Shop zu Shop. Marke plus Modellnummer ist ein viel besserer Schlüssel als der Titel, und Best Buy liefert model direkt mit. Rechne bei deinen wichtigsten Produkten mit etwas manueller Zuordnung.

Parallele Aufrufe Ohne 429

Sobald du mehr als ein paar Suchwörter verfolgst, werden sequenzielle Aufrufe langsam. In Python hat jede Methode einen asynchronen Zwilling auf AsyncClient, in Node.js gibt jede Methode ein Promise zurück. Begrenze die gleichzeitigen Aufrufe mit einem Semaphor:

import asyncio
from scrapeunblocker import AsyncClient

QUERIES = ["wireless headphones", "air fryer", "robot vacuum", "4k tv"]
STORES = ["walmart", "target", "bestbuy"]
CONCURRENCY = 10  # keep this below your plan's concurrency limit

async def search(su, sem, store, query):
    async with sem:
        method = getattr(su, f"{store}_search")
        return store, query, await method(query, max_results=48)

async def main():
    sem = asyncio.Semaphore(CONCURRENCY)
    async with AsyncClient() as su:
        jobs = [search(su, sem, s, q) for s in STORES for q in QUERIES]
        return await asyncio.gather(*jobs, return_exceptions=True)

results = asyncio.run(main())

Warum die Grenze wichtig ist: Pläne sind über gleichzeitige Anfragen begrenzt, nicht über Anfragen pro Sekunde. Die Limits liegen bei 20 für Pay as you go, 25 für Starter, 100 für Pro, 200 für Business, 300 für Scale und 400 für Ultimate. Eine Anfrage über dem Limit bekommt sofort ein 429 und wird nicht berechnet. Das SDK wiederholt ein 429 selbst mit Backoff, aber unter dem Limit zu bleiben hält deinen Lauf schnell und berechenbar. Details findest du unter Concurrency-Limits.

Fehler Wie in Einer Pipeline Behandeln, Nicht Wie in Einem Skript

Ein Skript, das du einmal laufen lässt, darf bei einem Fehler abstürzen. Ein Job, der jede Nacht läuft, sollte das nicht. Die SDKs werfen typisierte Fehler, alle Unterklassen von ScrapeUnblockerError, und wiederholen die vorübergehenden (429, 502, 503, 504 und Netzwerkfehler) bereits mit exponentiellem Backoff. Ein Plugin-Aufruf, dem die Zeit ausgeht, liefert jetzt 502 und wird nicht berechnet, also greift auch hier die eingebaute Wiederholung.

Was du selbst behandeln musst:

from scrapeunblocker import (
    Client,
    BudgetExceededError,
    ScrapeUnblockerError,
    ValidationError,
)

su = Client()

try:
    deals = su.bestbuy_search("oled tv", sort="discount", max_results=96)
except BudgetExceededError:
    # 402: this month's spend reached the limit you set. Stop, do not retry.
    raise SystemExit("Monthly budget reached, stopping the run")
except ValidationError as e:
    # 422: a parameter is missing or has the wrong type
    print("fix the request:", e.body)
except ScrapeUnblockerError as e:
    # anything that survived the built-in retries
    print("skipping this query:", e)

Der Fall BudgetExceededError ist neu. Du kannst jetzt in deinem Profil ein monatliches Budgetlimit festlegen. Sobald deine Ausgaben im Abrechnungszeitraum es erreichen, liefern Aufrufe 402, bis der nächste Zeitraum beginnt oder du das Limit anhebst. Für geplante Jobs ist das ein einfaches Sicherheitsnetz: Eine außer Kontrolle geratene Schleife sorgt nicht für eine böse Überraschung auf der Rechnung. Die SDKs wiederholen ein 402 nie, weil es sich nur ändert, wenn sich der Abrechnungsstatus ändert.

Die vollständige Liste der Statuscodes steht in der Fehlerreferenz.

Der Notausgang plugin()

Mit der Zeit kommen neue Plugins dazu, und deine installierte SDK-Version hat für das neueste vielleicht noch keine Methode. Für diesen Fall hat jeder Client einen generischen Aufruf, der den Pfad des Endpunkts und seine Parameter annimmt:

data = su.plugin("/marketplace/target-search", query="tv", max_results=24)

const data = await su.plugin("/marketplace/target-search", { query: "tv", max_results: 24 });

Zwei Details solltest du dir merken. Der Pfad ist der, der oben auf der Dokumentationsseite des Plugins steht. Und die Parameter tragen die Namen, die die API verwendet. In Node.js schreibst du hier also max_results, nicht das maxResults in camelCase, das die benannten Methoden erwarten.

Dieselben Plugins in Deinem KI-Assistenten

Wenn du Claude, ChatGPT oder einen anderen MCP-Client nutzt, brauchst du gar keinen Code. Mit den neuen Tools list_plugins und run_plugin findet der Assistent das passende Plugin und führt es aus, ausgehend von einer normalen Bitte wie “Find coffee makers on Target under $50 and compare them with Walmart’s.” Das Auflisten der Plugins ist kostenlos. Jeder Lauf wird wie eine API-Anfrage berechnet.

Die Einrichtung ist in Give Claude Web Access With the ScrapeUnblocker MCP Server und in der MCP-Dokumentation beschrieben.

FAQ

Brauche ich ein SDK, um Plugins zu nutzen? Nein. Jedes Plugin ist ein normaler HTTP-Endpunkt: ein POST mit den Parametern im Query-String und deinem Key im Header x-scrapeunblocker-key. Die SDKs bringen typisierte Fehler, Wiederholungen und Methodennamen mit, aber jeder HTTP-Client funktioniert.

Wie werden Plugin-Aufrufe abgerechnet? Ein Plugin-Lauf zieht vom selben Kontingent deines Plans ab wie jede andere API-Anfrage. Eine separate Abrechnung für Plugins gibt es nicht. Mit 429 abgelehnte Aufrufe, als 502 gemeldete Plugin-Timeouts und als 403 gemeldete Blockierungen werden nicht berechnet.

Warum fehlt bei manchen Produkten ein Feld? Plugins lassen Felder weg, die auf der Quellseite keinen Wert haben. Ein Produkt ohne Preisnachlass hat kein wasPrice, und eine Suchkachel ohne Marke hat kein brand. Lies Felder mit einem Standardwert, etwa .get() in Python, statt davon auszugehen, dass sie existieren.

Kann ich ein Plugin testen, bevor ich Code schreibe? Ja. Öffne die Plugins im Dashboard, fülle die Felder aus und starte den Lauf. Du bekommst das JSON und ein Snippet, das du direkt in dein Projekt kopieren kannst.

Wo Du Anfangen Kannst

Nimm eine Website, von der du bisher von Hand Daten sammelst, such ihr Plugin in der Plugin-Übersicht oder im Scraper-Katalog und ersetze deinen Scraper durch einen einzigen Methodenaufruf. Ergänze dann die Begrenzung der Nebenläufigkeit und die Fehlerbehandlung von oben, bevor du ihn nach Zeitplan laufen lässt.

ScrapeUnblocker kümmert sich hinter jedem Plugin um Blockaden, Rendering und Parsing, sodass dein Code nur ein paar Zeilen lang bleibt, egal welche Website am anderen Ende steht. Wenn du noch keinen Key hast, kannst du auf der Preisseite starten.