Bewertungen

Alle Bewertungsendpunkte: cURL/Python/Node-Beispiele; Quellen, Einstellungen, Liste, Übersicht, Details, Antworten, Bearbeiten, Archiv, Phrasen, Analysen.

Bewertungen sind die Sternebewertungen und Kommentare, die Kunden auf Google, Facebook und Yelp hinterlassen. Die API speichert jeweils eine Kopie, ermöglicht Ihnen das Antworten und berechnet Bewertungsanalysen. Die REST-Pfade verwenden reviews; die Antwortschlüssel und Titel der Referenzseiten verwenden interactions, den älteren internen Namen für dasselbe Objekt. Dieser Leitfaden verwendet durchgehend den Begriff Bewertung. Lesezugriffe benötigen einen Read (Lesen)-Schlüssel. Das Antworten, Bearbeiten, Archivieren und Ändern von Einstellungen erfordert einen Write (Schreiben)-Schlüssel; bei einem Schreibzugriff mit einem Read-Schlüssel wird 400 mit SY90016 zurückgegeben.

Endpunkte auf einen Blick

Die in Ihrem Tarif zulässigen Bewertungsquellen auflisten

GET /reviews/site-config gibt den Katalog der Bewertungsplattformen zurück, die das Konto nutzen darf. Der Endpunkt akzeptiert keine Parameter und gilt für das gesamte Konto. Speichern Sie das Ergebnis daher im Cache, statt den Endpunkt für jeden Standort aufzurufen. Die siteUrl-Werte sind die Hostnamen, die alle anderen Filter dieser Ressource akzeptieren.

curl https://listingsapi.com/api/v4/reviews/site-config \-H "Authorization: API $LISTINGSAPI_KEY"

{  "data": {    "interactionSiteConfig": [      { "site": "Google", "siteUrl": "maps.google.com" },      { "site": "Facebook", "siteUrl": "facebook.com" },      { "site": "Yelp", "siteUrl": "yelp.com" }    ]  }}

Lesen Sie data.interactionSiteConfig[] aus. Das Beispiel zeigt ein Konto im Launch-Tarif; die genaue Auswahl hängt vom Tarif und der Branche ab. Verwenden Sie siteUrl für den Filter siteUrls der Listenendpunkte und für siteUrls[].name beim Bearbeiten der Einstellungen.

Die für einen Standort konfigurierten Quellen auflisten

GET /locations/{locationId}/reviews/settings gibt einen Eintrag pro vom Tarif unterstützter Plattform zurück, einschließlich der URL, von der Bewertungen abgerufen werden. Dies ist das lesende Gegenstück zum unten beschriebenen Bearbeitungsendpunkt. Der Pfad akzeptiert die Base64-ID oder die einfache Zahl.

curl https://listingsapi.com/api/v4/locations/TG9jYXRpb246MTgwMDI4OQ==/reviews/settings \-H "Authorization: API $LISTINGSAPI_KEY"

{  "data": {    "interactionsSetting": {      "siteSettings": [        { "name": "maps.google.com", "url": null },        { "name": "facebook.com", "url": null },        { "name": "yelp.com", "url": null }      ]    }  }}

Lesen Sie data.interactionsSetting.siteSettings[] aus. Ein Wert ungleich null für url bedeutet, dass die Plattform verbunden ist und Bewertungen von dieser Seite abgerufen werden. Ein url mit dem Wert null bedeutet, dass die Plattform verfügbar, aber nicht konfiguriert ist. Google und Facebook werden automatisch eingetragen, wenn Sie diese Konten über OAuth verbinden, und können vom Bearbeitungsendpunkt nicht überschrieben werden. Yelp muss ausdrücklich angegeben werden.

Die Bewertungseinstellungen eines Standorts bearbeiten

POST /locations/reviews/settings/edit legt fest, auf welchen Quellen ein Standort überwacht wird und ab welcher Sternebewertung eine Bewertung als positiv gilt. Die Felder werden direkt im Body übergeben, ohne eine umschließende input-Struktur. Das Hinzufügen einer Quelle reiht einen Scraping-Auftrag in die Warteschlange ein, sodass die Bewertungen der neuen Plattform später eingehen und nicht in dieser Antwort enthalten sind.

curl -X POST https://listingsapi.com/api/v4/locations/reviews/settings/edit \-H "Authorization: API $LISTINGSAPI_KEY" \-H "Content-Type: application/json" \-d '{  "locationId": "TG9jYXRpb246MTgwMDI4OQ==",  "positiveInteractionThreshold": 4,  "siteUrls": [    { "name": "maps.google.com", "url": null },    { "name": "yelp.com", "url": "https://www.yelp.com/biz/blue-bottle-coffee-oakland" }  ]}'

{  "data": {    "editInteractionsSetting": {      "errors": null,      "interactionSetting": {        "locationId": "1800289",        "positiveInteractionThreshold": 4,        "siteSettings": [          { "name": "maps.google.com", "url": null, "monitored": true, "canRespond": true },          { "name": "yelp.com", "url": "https://www.yelp.com/biz/blue-bottle-coffee-oakland", "monitored": true, "canRespond": false }        ]      }    }  }}

Lesen Sie data.editInteractionsSetting.interactionSetting.siteSettings[] aus, um die gespeicherte Auswahl zu erhalten. monitored gibt an, dass die Quelle aktiv ist; canRespond gibt an, ob dort Inhaberantworten über die API veröffentlicht werden können. Eine bei der Validierung abgelehnte Quelle, etwa eine nicht erreichbare URL oder eine Plattform außerhalb des Tarifs, wird in errors zurückgegeben, wobei die Einstellung unverändert bleibt; prüfen Sie daher errors bei einer 200-Antwort. Die SDKs lösen in diesem Fall ValidationError aus.

Bewertungen für einen Standort auflisten

GET /locations/{locationId}/reviews ist eine Cursor-Verbindung unter data.interactions, mit den neuesten Bewertungen zuerst. first hat den Standardwert 20, daher liefert ein einzelner Aufruf niemals den vollständigen Verlauf. Array-Filter werden als JSON-Zeichenfolgen im Query-String übergeben und müssen URL-kodiert sein; das Beispiel für cURL verwendet dafür -G mit --data-urlencode.

Zusätzlich die optionalen Parameter category, categories und ratingFilter mit einem einzelnen Wert, die auf der Referenzseite aufgeführt sind.

curl -G "https://listingsapi.com/api/v4/locations/TG9jYXRpb246MTgwMDI4OQ==/reviews" \-H "Authorization: API $LISTINGSAPI_KEY" \--data-urlencode 'ratingFilters=[1,2]' \--data-urlencode 'responseStatus=["PENDING"]' \--data-urlencode 'sortOrder=["NEWEST_FIRST"]' \--data-urlencode 'first=25'

{  "data": {    "interactions": {      "pageInfo": { "hasNextPage": true, "endCursor": "SW50ZXJhY3Rpb246MV8xNTU0..." },      "edges": [        {          "node": {            "id": "9e26d2a8-a6ed-42ea-8454-47d1c92ea841",            "source": "maps.google.com",            "content": "nice place for family together",            "authorName": "vaibhav nakate",            "rating": 5,            "date": "2019-04-02T22:11:13.036997+00:00",            "type": "Review",            "responded": false,            "responseCount": 0,            "canRespond": true,            "permalink": "https://maps.google.com/maps?cid=..."          },          "cursor": "SW50ZXJhY3Rpb246MV8xNTU0..."        }      ],      "totalCount": 425    }  }}

Lesen Sie edges[].node aus. id übergeben Sie beim Antworten, und canRespond gibt an, ob diese Quelle Antworten von Inhabern akzeptiert. totalCount ist die Anzahl der Treffer in der gesamten Ergebnismenge, nicht auf dieser Seite. Beenden Sie das Blättern, wenn hasNextPage den Wert false hat oder eine Seite ein leeres edges zurückgibt; wenn eine Seitengrenze auf die älteste Bewertung fällt, folgt darauf eine leere Seite.

Alle Standorte mit der Sammelabfrage durchgehen

GET /rollup_interactions ist dieselbe Cursor-Verbindung unter data.rollupInteractions für alle Standorte, auf die der Schlüssel Zugriff hat, mit einer numerischen locationId an jedem Knoten. Sie akzeptiert dieselben Filter wie die standortbezogene Liste. Es gibt keinen Standortfilter; ein locationIds-Argument wird ignoriert, nicht abgelehnt. Keines der beiden SDKs bietet bisher eine Methode für diesen Endpunkt, daher verwenden die Beispiele requests und fetch.

curl -G "https://listingsapi.com/api/v4/rollup_interactions" \-H "Authorization: API $LISTINGSAPI_KEY" \--data-urlencode 'responseStatus=["PENDING"]' \--data-urlencode 'sortOrder=["NEWEST_FIRST"]' \--data-urlencode 'first=50'

{  "data": {    "rollupInteractions": {      "pageInfo": { "hasNextPage": true, "hasPreviousPage": false },      "edges": [        {          "node": {            "id": "9e26d2a8-a6ed-42ea-8454-47d1c92ea841",            "source": "maps.google.com",            "content": "Excellent service, highly recommend.",            "rating": 5,            "responded": false,            "canRespond": true,            "locationId": 1800289          },          "cursor": "SW50ZXJhY3Rpb246OWUyNmQyYTg="        }      ],      "totalCount": 1284    }  }}

Gruppieren Sie die Knoten nach locationId, der databaseId des Geschäfts. pageInfo der Sammelabfrage enthält möglicherweise kein endCursor. Verwenden Sie daher cursor der letzten Kante als after; die beiden Werte sind gleichwertig. Begrenzen Sie geplante Durchläufe mit startDate und endDate, anstatt den Verlauf erneut zu lesen, und beachten Sie Retry-After bei einer 429.

Bewertungen anhand ihrer ID abrufen

GET /reviewDetails gibt aktuelle Kopien gespeicherter Bewertungen ohne Paginierung zurück. Die Antwort ist ein einfaches Array unter data.interactionDetails.interactions, ohne edges oder pageInfo, und jede Bewertung enthält ihr responses. Verwenden Sie den Endpunkt, um eine Beobachtungsliste erneut mit aktuellen Daten zu befüllen und die responseId zu ermitteln, die Sie zum Bearbeiten oder Archivieren benötigen.

curl -G "https://listingsapi.com/api/v4/reviewDetails" \-H "Authorization: API $LISTINGSAPI_KEY" \--data-urlencode 'interactionIds=["b2fa765e-c62b-4e0b-b1d6-1c67c855f5e0"]'

{  "data": {    "interactionDetails": {      "interactions": [        {          "id": "b2fa765e-c62b-4e0b-b1d6-1c67c855f5e0",          "source": "maps.google.com",          "content": "Great place for dessert!",          "rating": 5,          "responded": true,          "responseCount": 1,          "canRespond": true,          "responses": [            {              "id": "2090753a-ece6-4837-8336-8494ad308523",              "content": "Thank you so much for the kind words!",              "interactionStatus": "CONFIRMED",              "editedResponse": false            }          ]        }      ]    }  }}

responses[].id ist die responseId für die Endpunkte zum Bearbeiten und Archivieren. Bei einer ID aus einem anderen Konto wird 200 mit interactionDetails: null und einem SY90001-Fehler zurückgegeben. Prüfen Sie daher vor dem Zugriff per Index auf null.

Felder für Bewertungen und Antworten

Die Attributreferenz ist eine reine Dokumentationsseite, die alle Felder des Bewertungsobjekts und des Antwortobjekts auflistet. Die Felder, die Sie am häufigsten verwenden werden:

Jede Antwort in responses[] enthält id, content, authorName, date, interactionStatus, editedResponse, respondedWith (Vorlagen-ID) und remarks (Fehlerdetails). interactionStatus durchläuft diese Zustände:

Eine Antwort als Inhaber veröffentlichen

POST /locations/reviews/respond veröffentlicht eine öffentliche Antwort auf der Quellplattform. Die Felder werden direkt im Body angegeben. Die Antwort wird sofort angenommen und asynchron übermittelt, daher beginnt interactionStatus mit CREATED. Prüfen Sie zuerst canRespond der Bewertung.

curl -X POST https://listingsapi.com/api/v4/locations/reviews/respond \-H "Authorization: API $LISTINGSAPI_KEY" \-H "Content-Type: application/json" \-d '{  "interactionId": "9e26d2a8-a6ed-42ea-8454-47d1c92ea841",  "responseContent": "Thank you for visiting Jenny Home: we are glad you enjoyed your experience!"}'

{  "data": {    "respondToInteraction": {      "interaction": {        "id": "2090753a-ece6-4837-8336-8494ad308523",        "interactionId": "9e26d2a8-a6ed-42ea-8454-47d1c92ea841",        "content": "Thank you for visiting Jenny Home: we are glad you enjoyed your experience!",        "interactionStatus": "CREATED",        "editedResponse": false      },      "errors": null    }  }}

Bewahren Sie interaction.id auf: Dieser Wert dient als responseId zum Bearbeiten und Archivieren. Eine abgelehnte Antwort wird als 200 zurückgegeben, wobei errors innerhalb von data.respondToInteraction ausgefüllt ist; lesen Sie daher den Body; die SDKs lösen ValidationError aus. Rufen Sie die Bewertung nach einer kurzen Wartezeit erneut anhand ihrer ID ab, um zu sehen, ob die Antwort COMPLETED oder CONFIRMED erreicht hat.

Eine Antwort bearbeiten

POST /locations/reviews/respond/edit ändert den Text einer vorhandenen Antwort. Die Änderung wird erneut an die Plattform übermittelt, daher kehrt interactionStatus zu CREATED zurück und editedResponse wird zu true, sobald sie dort angekommen ist. Bevorzugen Sie dieses Vorgehen auf Plattformen, die nur eine Antwort zulassen, gegenüber dem Archivieren und erneuten Veröffentlichen.

curl -X POST https://listingsapi.com/api/v4/locations/reviews/respond/edit \-H "Authorization: API $LISTINGSAPI_KEY" \-H "Content-Type: application/json" \-d '{  "reviewId": "9e26d2a8-a6ed-42ea-8454-47d1c92ea841",  "responseId": "2090753a-ece6-4837-8336-8494ad308523",  "responseContent": "Thank you again: we have updated our reply to include our new store hours."}'

{  "data": {    "editResponse": {      "status": "true",      "reviewId": "9e26d2a8-a6ed-42ea-8454-47d1c92ea841",      "responseId": "2090753a-ece6-4837-8336-8494ad308523"    }  }}

status ist die Zeichenfolge "true", wenn die Änderung angenommen wurde. Bestätigen Sie den neuen Wortlaut durch einen Detailabruf und prüfen Sie interactionStatus der Antwort.

Eine Antwort archivieren

POST /locations/reviews/respond/archive entfernt eine Antwort aus responses der Bewertung, die wir auf unserer Seite führen. Dies ist eine logische Löschung: Eine bereits auf Google, Yelp oder Facebook veröffentlichte Antwort bleibt dort bestehen. Verwenden Sie diese Funktion, um einen fehlgeschlagenen oder ersetzten Entwurf zu entfernen; verwenden Sie für bereits veröffentlichte Antworten die Bearbeitungsfunktion.

curl -X POST https://listingsapi.com/api/v4/locations/reviews/respond/archive \-H "Authorization: API $LISTINGSAPI_KEY" \-H "Content-Type: application/json" \-d '{ "responseId": "2090753a-ece6-4837-8336-8494ad308523" }'

{  "data": {    "archiveResponse": {      "status": "true"    }  }}

Nach der Archivierung sinkt responseCount der Bewertung und responded spiegelt die verbleibenden Antworten wider.

Wiederkehrende Formulierungen von Kunden auflisten

GET /review-phrases gibt unter data.newReviewPhrases ein einfaches Array zurück, mit einem Eintrag pro wiederkehrender Formulierung und jeweils Statistiken, die ausschließlich aus den Bewertungen berechnet werden, die diese Formulierung enthalten. Es ist nicht paginiert; begrenzen Sie es mit phraseCount. Jeder Filter ist optional und die Filter lassen sich kombinieren, sodass ratingFilters=[1,2] zusammen mit einem startDate die Beschwerden des letzten Quartals liefert.

Hinzu kommen der optionale Parameter categories sowie die veralteten Parameter category und ratingFilter für jeweils einen einzelnen Wert, die auf der Referenzseite aufgeführt sind.

curl -G "https://listingsapi.com/api/v4/review-phrases" \-H "Authorization: API $LISTINGSAPI_KEY" \--data-urlencode 'locationIds=[1800289]' \--data-urlencode 'ratingFilters=[1,2]' \--data-urlencode 'startDate=2026-06-01' \--data-urlencode 'endDate=2026-08-31' \--data-urlencode 'phraseCount=10'

{  "data": {    "newReviewPhrases": [      {        "reviewPhrase": "friendly staff",        "phraseStats": {          "stats": [            { "name": "total-reviews", "value": 46, "delta": 12.5, "abs": 5 },            { "name": "overall-rating", "value": 4.7, "delta": 1.1, "abs": 0.05 }          ]        }      },      {        "reviewPhrase": "long wait",        "phraseStats": {          "stats": [            { "name": "total-reviews", "value": 11, "delta": 37.5, "abs": 3 },            { "name": "overall-rating", "value": 2.9, "delta": -8.4, "abs": -0.27 }          ]        }      }    ]  }}

total-reviews gibt an, wie oft die Formulierung vorkommt, overall-rating ist die durchschnittliche Bewertung dieser Bewertungen, delta ist die prozentuale Veränderung gegenüber dem vorherigen Zeitraum und abs ist die absolute Veränderung. Ein 403 mit SY90003 bedeutet, dass der Schlüssel keinen Lesezugriff auf einen der angeforderten Standorte hat.

Die Bewertungs-KPIs für einen Standort abrufen

GET /locations/{locationId}/review-analytics-overview gibt unter data.interactionsAnalyticsStats.stats vier Kennzahlen zurück. Der Datumsbereich ist optional; er grenzt den Zeitraum ein, über den die Werte und ihre Veränderungen berechnet werden. Jeder delta-Wert ist die prozentuale Veränderung gegenüber dem vorherigen Zeitraum gleicher Länge.

curl "https://listingsapi.com/api/v4/locations/TG9jYXRpb246MTgwMDI4OQ==/review-analytics-overview?startDate=2026-08-01&endDate=2026-08-31" \-H "Authorization: API $LISTINGSAPI_KEY"

{  "data": {    "interactionsAnalyticsStats": {      "stats": [        { "name": "total-reviews", "value": 128, "delta": 6.67 },        { "name": "new-reviews", "value": 9, "delta": -25 },        { "name": "overall-rating", "value": 4.43, "delta": 2.31 },        { "name": "review-response-rate", "value": 62.5, "delta": 12.5 }      ]    }  }}

Bei einem neuen Konto ohne vorherigen Zeitraum wird für delta der Wert 100 gemeldet; interpretieren Sie daher die Veränderungen des ersten Monats nicht als Wachstum.

Täglichen Bewertungsverlauf abrufen

GET /locations/{locationId}/review-analytics-timeline gibt unter data.interactionsChartData.data einen Eintrag pro Tag zurück. Übergeben Sie startDate und endDate, wenn der Zeitraum des Diagramms relevant ist; wenn Sie diese weglassen, wählt der Dienst einen eigenen Zeitraum. Fügen Sie site hinzu, um eine einzelne Quelle darzustellen.

curl "https://listingsapi.com/api/v4/locations/TG9jYXRpb246MTgwMDI4OQ==/review-analytics-timeline?startDate=2026-08-01&endDate=2026-08-31&site=maps.google.com" \-H "Authorization: API $LISTINGSAPI_KEY"

{  "data": {    "interactionsChartData": {      "data": [        { "date": "2026-08-01", "interactionCount": 4, "averageRating": 4.5 },        { "date": "2026-08-02", "interactionCount": 0, "averageRating": null },        { "date": "2026-08-03", "interactionCount": 7, "averageRating": 4.285714285714286 }      ]    }  }}

Stellen Sie interactionCount als Balken und averageRating als Linie dar. Der Durchschnitt bezieht sich ausschließlich auf den jeweiligen Tag, ist kein gleitender Durchschnitt und hat an Tagen ohne Bewertungen den Wert null; lassen Sie daher eine Lücke, statt null darzustellen.

Bewertungsanalysen nach Quelle aufschlüsseln

GET /locations/{locationId}/review-analytics-sites-stats gibt unter data.interactionsSitesStats.stats einen Eintrag pro Bewertungsquelle zurück. Ermitteln Sie damit, welche Plattform den Durchschnitt verändert hat.

curl "https://listingsapi.com/api/v4/locations/TG9jYXRpb246MTgwMDI4OQ==/review-analytics-sites-stats?startDate=2026-08-01&endDate=2026-08-31" \-H "Authorization: API $LISTINGSAPI_KEY"

{  "data": {    "interactionsSitesStats": {      "stats": [        {          "key": "google",          "siteUrl": "maps.google.com",          "averageRating": { "value": 4.6, "delta": 2.2 },          "totalInteractions": { "value": 412, "delta": 6.1 },          "newInteractions": { "value": 24, "delta": 33.3 },          "recency": "2026-09-06T14:12:00Z",          "baseRating": 4.5,          "baseInteractions": 388,          "humanizedRecency": "3 days ago"        },        {          "key": "facebook",          "siteUrl": "facebook.com",          "averageRating": { "value": 4.1, "delta": -1.4 },          "newInteractions": { "value": 0, "delta": -100 },          "recency": null,          "humanizedRecency": null        }      ]    }  }}

averageRating, totalInteractions und newInteractions enthalten jeweils value und delta; baseRating und baseInteractions sind die Werte zu Beginn des Zeitraums, von dem aus das Delta gemessen wird. recency ist der Zeitstempel der neuesten Bewertung und hat den Wert null, wenn die Quelle noch nie eine Bewertung zurückgegeben hat. Ein Wert von 0 für newInteractions zusammen mit einem Monate alten recency bedeutet in der Regel, dass die Verbindung zur Quelle nicht mehr aktuell ist; prüfen Sie daher die Quellen des Standorts.

Fehler, die auftreten können

Schreibvorgänge können auch 200 zurückgeben, wobei errors innerhalb von data.<op> befüllt ist; lesen Sie daher den Antworttext jedes Schreibvorgangs. Die vollständige Liste finden Sie unter Fehlercodes.

Nächste Schritte

• Bewertungen abrufen: Erstellen Sie eine Warteschlange für ausstehende Bewertungen und lassen Sie sich per Webhook benachrichtigen.
• Auf Bewertungen antworten: antworten, bestätigen, bearbeiten, archivieren.
• Bewertungsanalysen: Kennzahlenübersicht, Diagramm, Beschwerdeübersicht, tägliche Momentaufnahmen.
• Analysen: Profilkennzahlen von Google, Facebook und Bing für denselben Standort.
• Referenzübersicht: Bewertungen. SDKs: Bewertungen mit Python, Bewertungen mit Node.