Wählen Sie eine Integrationsmethode

Vergleichen Sie REST API, Python- und Node-SDKs, MCP-Server und Webhooks anhand der Architektur und Integrationsanforderungen Ihrer Anwendung.

Alle Integrationsmethoden verwenden denselben API-Schlüssel und dieselbe Basis-URL: https://listingsapi.com/api/v4. Sie können die REST API oder ein SDK für API-Anfragen, Webhooks für ereignisgesteuerte Aktualisierungen und den MCP-Server für die Integration mithilfe eines KI-Agenten verwenden.

1. Wählen Sie, wie Sie die API aufrufen möchten

REST API. Verwenden Sie die REST API, um direkt über HTTP auf alle Endpunkte zuzugreifen. Ihre Anwendung muss die Antwort parsen, beide Paginierungsmethoden verarbeiten und das Array errors[] auf API-Fehler prüfen.

Python SDK. Installieren Sie das Python SDK mit pip install listingsapi. Das SDK stellt Ressourcenklassen über Schnittstellen wie client.locations und client.reviews bereit. Es verarbeitet die Cursor-Paginierung mit auto_paging_iter(), wiederholt Anfragen, die Antworten mit 429 oder 5xx zurückgeben, und validiert Standort-Payloads in locations.add(), bevor es die API-Anfrage sendet. Lesen Sie Python SDK.

Node SDK. Installieren Sie das Node SDK mit npm install listingsapi-js. Es erfordert Node.js 18 oder höher, enthält TypeScript-Typdefinitionen und hat keine Laufzeitabhängigkeiten. SDK-Methoden stehen direkt auf der Client-Instanz zur Verfügung, beispielsweise client.fetchAllLocations(). Setzen Sie fetchAll: true, um alle paginierten Ergebnisse in einer einzigen Antwort abzurufen. Numerische IDs werden automatisch Base64-kodiert, bevor API-Anfragen gesendet werden. Lesen Sie Node SDK.

MCP-Server. Verbinden Sie KI-Clients wie Claude, ChatGPT, Cursor und Gemini über Streamable HTTP mit dem ListingsAPI-MCP-Server unter https://listingsapi.com/mcp. Eine lokale Installation des MCP-Servers ist nicht erforderlich. Der Server stellt Tools bereit, mit denen Sie die ListingsAPI-Dokumentation durchsuchen, REST-Endpunkte ermitteln und unterstützte API-Operationen ausführen können. Die Authentifizierung erfolgt über einen API-Schlüssel oder OAuth. Öffnen Sie /dashboard/mcp, um die Client-Konfiguration, die verfügbaren MCP-Tools und die für jedes Tool erforderliche Berechtigungsstufe des API-Schlüssels einzusehen. Einen KI-Agenten über MCP verbinden.

Webhooks. Verwenden Sie Webhooks zusammen mit der REST API, den SDKs oder dem MCP-Server, um ereignisgesteuerte Aktualisierungen zu erhalten. Wenn sich ein Standort, ein Eintrag, eine Bewertung oder ein Beitrag ändert, sendet ListingsAPI eine HTTP-Anfrage mit der Methode POST an die für Ihr Konto konfigurierte Webhook-URL. So kann Ihre Anwendung Änderungen verarbeiten, ohne die API regelmäßig auf Aktualisierungen abzufragen. Lesen Sie Übersicht über Webhooks.

2. Machen Sie sich mit dem Authentifizierungsmodell vertraut

Die REST API und die SDKs authentifizieren Anfragen mit einem API-Schlüssel. Übergeben Sie den Schlüssel im HTTP-Anfrageheader Authorization unter Verwendung des Authentifizierungsschemas API:

Authorization: API <YOUR_API_KEY>

API-Schlüssel haben entweder Read (Lesezugriff) oder Write (Schreibzugriff). Ein Read-Schlüssel ermöglicht den Zugriff auf Leseoperationen, einschließlich Abfragen und Berichten. Für Operationen, die Ressourcen erstellen oder aktualisieren, ist ein Write-Schlüssel erforderlich. Wenn Sie einen Read-Schlüssel an einen Schreibendpunkt senden, gibt der Endpunkt HTTP 400 mit dem Fehlercode SY90016 zurück.

API-Schlüssel sind auf ein Konto beschränkt. Anfragen mit Schlüsseln desselben Kontos verbrauchen dasselbe kontoweite Kontingent für das Anfragelimit.

Der MCP-Server unterstützt auch die Authentifizierung über OAuth. MCP-Clients können sich über den Browser mit OAuth authentifizieren, anstatt einen API-Schlüssel anzugeben. Anfragen an die REST API und SDK-Anfragen werden über den Header Authorization authentifiziert. Einzelheiten zur Konfiguration finden Sie in der Dokumentation unter Authentifizierung.

3. Die Paginierungsmodelle verstehen

REST-Endpunkte zum Auflisten verwenden entweder eine cursorbasierte oder eine offsetbasierte Paginierung. Die SDKs abstrahieren diese Paginierungsmodelle.

Cursorbasierte Endpunkte akzeptieren first und after. Die Ergebnisse werden über edges[].node zurückgegeben, und pageInfo.endCursor liefert den Cursor für die nächste Anfrage.

Offsetbasierte Endpunkte akzeptieren page und perPage. Die Ergebnisse werden in records[] zurückgegeben, und pageInfo.totalRecords gibt die Gesamtzahl der verfügbaren Datensätze an.

Die folgenden Beispiele führen denselben Vorgang zum Auflisten von Standorten mit drei Integrationsmethoden aus. Bei der cURL-Implementierung muss die Anwendung die Struktur der API-Antwort direkt auswerten.

curl "https://listingsapi.com/api/v4/locations?first=5" \-H "Authorization: API $LISTINGSAPI_KEY" # Read data.allLocations.edges[].node, then pass# data.allLocations.pageInfo.endCursor back as ?after= for the next page.

Bei allen Integrationsmethoden werden API-Fehler im Array errors[] zurückgegeben, wobei jeder Fehlermeldung ein SY-Fehlercode vorangestellt wird. Schreibanfragen können HTTP 200 mit success: false zurückgeben, daher muss der Antworttext geprüft werden, bevor der Vorgang als erfolgreich behandelt wird.

Wenn das Konto sein Anfragelimit überschreitet, gibt die API HTTP 429 mit einem Retry-After-Header zurück. Der Launch-Tarif unterstützt bis zu 10 Anfragen pro Minute. Einzelheiten finden Sie in der Dokumentation zu Fehlercodes und Anfragelimits.

4. Zwischen Webhooks und Polling wählen

Verwenden Sie Polling, wenn Ihre Anwendung den Zustand von Ressourcen nach einem festgelegten Zeitplan benötigt, etwa für eine nächtliche Synchronisierung aller Standorte, oder wenn das benötigte Ereignis keine Webhooks unterstützt. Verwenden Sie Webhooks, wenn Ihre Anwendung Änderungen verarbeiten muss, sobald sie auftreten, etwa beim Eingang einer neuen Bewertung, einer Statusänderung eines Eintrags oder der Ablehnung eines Google-Beitrags.

Konfigurieren Sie unter /dashboard/webhooks eine Webhook-URL pro Konto. Jede Webhook-Anfrage enthält einen X-ListingsAPI-Signature-Header im folgenden Format:

X-ListingsAPI-Signature: sha256=<base64 HMAC>

Der Webhook-Endpunkt muss innerhalb von 5 Sekunden eine 2xx-Antwort zurückgeben. Fehlgeschlagene Zustellungen werden nicht wiederholt.

Verwenden Sie das Webhook-Ereignis als Auslöser, um den aktuellen Zustand der Ressource über die API abzurufen. Da Webhook-Zustellungen nicht wiederholt werden, führen Sie einen geplanten Abgleichprozess aus, um möglicherweise verpasste Aktualisierungen zu erkennen. Ein Implementierungsbeispiel finden Sie unter Mit Webhooks auf Ereignisse reagieren.

5. Vergleich auf einen Blick

Nächste Schritte

• Einen Standort hinzufügen: Ihr erster Schreibaufruf mit der von Ihnen gewählten Option.
• Mit Webhooks auf Ereignisse reagieren: Richten Sie einen Empfänger für signierte Anfragen ein.
• Python SDK und Node SDK: Installieren und konfigurieren Sie die SDKs und lesen Sie die Methodentabellen.
• Authentifizierung, Anfragelimits und Fehlercodes: die drei Referenzen, die für alle Optionen gelten.