Bewertungen für einen Standort oder Ihr Konto abrufen

Rufen Sie neueste Bewertungen je Standort oder kontoweit ab, filtern Sie niedrige ohne Antwort, blättern Sie per Cursor und erhalten Sie Webhook-Meldungen.

Bewertungen werden in der API als interactions bezeichnet. Jede Bewertung von Google, Facebook oder Yelp wird in einer gemeinsamen Liste pro Standort sowie in einer Zusammenfassung für das Konto zurückgegeben, sodass eine einzige Integration jede von Ihnen verbundene Quelle abdeckt.

1. Die neuesten Bewertungen für einen Standort auflisten

GET /locations/{locationId}/reviews ist eine Cursor-Verbindung unter data.interactions. Die Ergebnisse werden mit den neuesten zuerst zurückgegeben, und der Standardwert für first ist 20, sodass ein einzelner Aufruf nie den vollständigen Verlauf liefert. Der Pfad akzeptiert die Base64-ID oder die reine Zahl.

Latest reviews

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

JSON

{  "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",            "responded": false,            "responseCount": 0,            "canRespond": true,            "permalink": "https://maps.google.com/maps?cid=..."          },          "cursor": "SW50ZXJhY3Rpb246MV8xNTU0..."        }      ],      "totalCount": 425    }  }}

Lesen Sie data.interactions.edges[].node. id ist eine einfache UUID, keine Base64-Relay-ID, und wird beim Antworten übergeben. totalCount ist die Anzahl der Treffer im gesamten Ergebnissatz, nicht auf dieser Seite. canRespond gibt an, ob diese Quelle Antworten des Inhabers über die API akzeptiert.

2. Nach niedrigen Bewertungen ohne Antwort filtern

Array-Filter werden als JSON-Zeichenfolgen im Query-String übergeben: ratingFilters=[1,2] beschränkt die Ergebnisse auf Bewertungen mit einem oder zwei Sternen, und responseStatus=["PENDING"] beschränkt sie auf Bewertungen ohne Antwort des Inhabers. Die Klammern und Anführungszeichen müssen URL-kodiert sein, daher verwendet das cURL-Beispiel -G mit --data-urlencode, wodurch jeder Wert für Sie kodiert und an die URL angehängt wird. Der entsprechende wörtliche Query-String lautet ratingFilters=%5B1%2C2%5D&responseStatus=%5B%22PENDING%22%5D.

Unanswered 1-2 stars

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=50'

Diese Filter können Sie kombinieren:

Parameter	Werte	Hinweise
`siteUrls`	`["maps.google.com"]`, `["facebook.com"]`, `["yelp.com"]`	Hostnamen aus Bewertungsquellen für ein Konto auflisten.
`ratingFilters`	`[1,2]` und so weiter	Sternebewertungen, die berücksichtigt werden sollen.
`responseStatus`	`["PENDING"]` oder `["RESPONDED"]`	Ob eine Antwort des Inhabers vorhanden ist.
`sortOrder`	`["NEWEST_FIRST"]`, `["OLDEST_FIRST"]`, `["LAST_RESPONDED"]`	Standardmäßig werden die neuesten zuerst angezeigt.
`startDate`, `endDate`	`YYYY-MM-DD`	Einfache Zeichenfolgen, kein JSON.
`searchString`	Freitext	Volltextsuche im Bewertungstext.

3. Mithilfe von Cursorn durch die Ergebnisse blättern

Übergeben Sie pageInfo.endCursor als after zurück. Beenden Sie den Vorgang, wenn hasNextPage den Wert false hat oder eine Seite ein leeres edges-Array zurückgibt; liegt eine Seitengrenze auf der ältesten Bewertung, folgt darauf eine leere Seite. Beide SDKs können die Seiten für Sie abrufen.

curl "https://listingsapi.com/api/v4/locations/TG9jYXRpb246MTgwMDI4OQ==/reviews?first=50&after=SW50ZXJhY3Rpb246MV8xNTU0..." \-H "Authorization: API $LISTINGSAPI_KEY"

Jede Anfrage wird auf Ihr Anfragelimit angerechnet, und für einen Standort mit 425 Bewertungen sind bei first=50 neun Aufrufe erforderlich. Warten Sie bei 429 auf Retry-After, bevor Sie die nächste Seite abrufen. Begrenzen Sie bei einer geplanten Synchronisierung den Durchlauf mit startDate und endDate, statt den Verlauf erneut abzurufen. Siehe Anfragelimits.

4. Das gesamte Konto über die Zusammenfassung abrufen

GET /rollup_interactions gibt unter data.rollupInteractions dieselben Knoten für alle Standorte zurück, auf die der Schlüssel Zugriff hat, wobei jeder Knoten ein locationId enthält. Der Endpunkt akzeptiert dieselben Filter sowie zusätzlich tag, dessen Standardwert all ist. Es gibt keinen Standortfilter; gruppieren Sie die Ergebnisse selbst nach locationId. Keines der beiden SDKs stellt bisher eine eigene Methode für diesen Endpunkt bereit, daher rufen ihn die SDK-Beispiele mit requests und fetch auf.

Account-wide pending

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'

Jeder Knoten hat dieselbe Struktur wie in Schritt 1 und enthält zusätzlich ein numerisches locationId, die databaseId des Standorts. In pageInfo der Zusammenfassung kann endCursor fehlen; verwenden Sie daher cursor der letzten Kante als after; die beiden Werte sind gleichwertig.

5. Vollständige Details anhand der ID abrufen

Wenn Sie IDs gespeichert haben, gibt GET /reviewDetails aktuelle Kopien ohne Paginierung zurück. interactionIds ist ein JSON-Array, das wie die anderen Filter URL-kodiert wird. Die Antwort ist ein einfaches Array unter data.interactionDetails.interactions, und jede interaction enthält ihr responses.

Details by id

curl -G "https://listingsapi.com/api/v4/reviewDetails" \-H "Authorization: API $LISTINGSAPI_KEY" \--data-urlencode 'interactionIds=["9e26d2a8-a6ed-42ea-8454-47d1c92ea841"]'

JSON

{  "data": {    "interactionDetails": {      "interactions": [        {          "id": "9e26d2a8-a6ed-42ea-8454-47d1c92ea841",          "responded": true,          "responseCount": 1,          "responses": [            {              "id": "2090753a-ece6-4837-8336-8494ad308523",              "content": "Thank you so much for the kind words!",              "interactionStatus": "CONFIRMED"            }          ]        }      ]    }  }}

Bei einer ID aus einem anderen Konto wird 200 mit interactionDetails: null und einem SY90001-Fehler zurückgegeben; prüfen Sie daher auf null, bevor Sie per Index zugreifen.

6. Webhook-Ereignisse statt Polling empfangen

Wenn eine Webhook-URL konfiguriert ist, wird ein interaction.review-Ereignis ausgelöst, sobald eine Bewertung eingelesen wird oder sich ändert. Die Bewertungsfelder befinden sich unter data.interaction, nicht direkt unter data, und data.interaction.id ist dieselbe UUID, die die Liste zurückgibt.

Zwei Hinweise. location_id wird bei diesem Ereignis ohne Normalisierung weitergegeben: Der Wert kann eine numerische Zeichenfolge oder null sein. Konvertieren Sie ihn daher selbst, anstatt sich auf den Typ zu verlassen. Und derselbe Wert für id wird bei jeder Änderung der Bewertung erneut übermittelt. Behandeln Sie das Ereignis daher als Anlass, die Bewertung erneut abzurufen, und nicht als einmaliges Einfügen. Die Zustellung erfolgt mit einem einzigen Versuch ohne Wiederholung. Behalten Sie daher die regelmäßige Prüfung aus Schritt 4 als Absicherung bei. Die Einrichtung ist unter Mit Webhooks auf Ereignisse reagieren beschrieben.

Nächste Schritte

Auf Bewertungen antworten: Antworten Sie auf die gerade gefundenen ausstehenden Bewertungen und bearbeiten oder archivieren Sie anschließend die Antwort.
Bewertungsanalysen: Bewertungspunktzahl, Anzahl der Bewertungen und Antwortrate für denselben Standort.
Referenz: Interaktionen auflisten, Zusammengefasste Interaktionen abrufen, Interaktionen anhand von IDs abrufen, Interaktionsattribute.
SDKs: Bewertungen mit Python, Bewertungen mit Node.