Recupera recensioni per una sede o tutto il tuo account

Elenca le ultime recensioni per sede, filtra le valutazioni basse senza risposta, scorri con cursori, esamina l'account e ricevi notifiche via webhook.

Nell'API le recensioni sono chiamate interactions. Ogni recensione di Google, Facebook o Yelp viene restituita in un unico elenco per sede e in un'unica aggregazione per l'account, quindi una sola integrazione copre tutte le fonti che colleghi.

1. Elenca le recensioni più recenti per una sede

GET /locations/{locationId}/reviews è una connessione basata su cursori disponibile in data.interactions. I risultati sono ordinati dal più recente e first ha come valore predefinito 20, quindi una singola chiamata non restituisce mai l'intera cronologia. Il percorso accetta l'id in base64 o il numero semplice.

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    }  }}

Leggi data.interactions.edges[].node. id è un semplice UUID, non un id Relay in base64, ed è il valore che passi quando rispondi. totalCount è il numero di corrispondenze nell'intero insieme di risultati, non in questa pagina. canRespond indica se quella fonte accetta risposte del proprietario tramite l'API.

2. Filtra le recensioni con valutazioni basse senza risposta

I filtri di tipo array sono stringhe JSON nella query string: ratingFilters=[1,2] seleziona le recensioni con 1 e 2 stelle e responseStatus=["PENDING"] seleziona quelle senza risposta del proprietario. Le parentesi quadre e le virgolette devono essere codificate per l'URL, quindi l'esempio cURL usa -G con --data-urlencode, che codifica ogni valore e lo aggiunge all'URL per te. La query string letterale equivalente è 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'

I filtri che puoi combinare:

Parametro	Valori	Note
`siteUrls`	`["maps.google.com"]`, `["facebook.com"]`, `["yelp.com"]`	Nomi host ottenuti tramite Elenca le fonti delle recensioni per un account.
`ratingFilters`	`[1,2]` e così via	Valutazioni in stelle da selezionare.
`responseStatus`	`["PENDING"]` o `["RESPONDED"]`	Indica se esiste una risposta del proprietario.
`sortOrder`	`["NEWEST_FIRST"]`, `["OLDEST_FIRST"]`, `["LAST_RESPONDED"]`	Per impostazione predefinita, i risultati sono ordinati dal più recente.
`startDate`, `endDate`	`YYYY-MM-DD`	Stringhe semplici, non JSON.
`searchString`	testo libero	Ricerca a testo integrale nel corpo della recensione.

3. Scorri le pagine con i cursori

Passa nuovamente pageInfo.endCursor come after. Fermati quando hasNextPage è false o quando una pagina restituisce un array edges vuoto; se il limite della pagina coincide con la recensione più vecchia, segue una pagina vuota. Entrambi gli SDK possono leggere le pagine per te.

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

Ogni richiesta viene conteggiata nel tuo limite di frequenza e una sede con 425 recensioni richiede 9 chiamate con first=50. In caso di 429, attendi Retry-After prima di richiedere la pagina successiva. Per una sincronizzazione pianificata, limita l'intervallo dell'esecuzione con startDate e endDate invece di rileggere la cronologia. Consulta Limiti di frequenza.

4. Passa in rassegna tutto l'account con l'aggregazione

GET /rollup_interactions restituisce gli stessi nodi per tutte le sedi a cui la chiave ha accesso, in data.rollupInteractions, con un locationId su ogni nodo. Accetta gli stessi filtri più tag, il cui valore predefinito è all. Non esiste un filtro per sede; raggruppa tu i risultati per locationId. Nessuno dei due SDK offre ancora un metodo per questo endpoint, quindi gli esempi degli SDK lo chiamano con requests e fetch.

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'

Ogni nodo ha la stessa struttura del passaggio 1, più un locationId numerico, ossia il databaseId del punto vendita. Il pageInfo dell'aggregazione può omettere endCursor, quindi usa il cursor dell'ultimo edge come after; i due valori sono equivalenti.

5. Recupera i dettagli completi tramite id

Quando hai degli id memorizzati, GET /reviewDetails restituisce copie aggiornate senza paginazione. interactionIds è un array JSON, codificato per l'URL come gli altri filtri. La risposta è un semplice array in data.interactionDetails.interactions e ogni interaction include il proprio 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"            }          ]        }      ]    }  }}

Un id di un altro account restituisce 200 con interactionDetails: null e un errore SY90001, quindi verifica la presenza di null prima di accedere agli elementi tramite indice.

6. Ricevi eventi webhook invece di effettuare il polling

Con un URL per i webhook configurato, viene generato un evento interaction.review quando una recensione viene acquisita o modificata. I campi della recensione si trovano sotto data.interaction, non direttamente sotto data, e data.interaction.id è lo stesso UUID restituito dall'elenco.

Due avvertenze. location_id in questo evento viene trasmesso senza normalizzazione: può essere una stringa numerica o null, quindi convertilo tu invece di fare affidamento sul tipo. Inoltre, lo stesso id arriva di nuovo ogni volta che la recensione cambia, quindi tratta l'evento come un segnale per rileggere la recensione, non come un inserimento da eseguire una sola volta. La consegna prevede un solo tentativo, senza nuovi tentativi, quindi mantieni la scansione periodica del passaggio 4 come misura di riserva. La configurazione è descritta in Reagisci agli eventi con i webhook.

Passaggi successivi

Rispondi alle recensioni: rispondi alle recensioni in attesa di risposta che hai appena trovato, poi modifica o archivia la risposta.
Analisi delle recensioni: valutazione, volume e tasso di risposta per la stessa sede.
Riferimenti: Elenca le interazioni, Ottieni le interazioni aggregate, Ottieni le interazioni per ID, Attributi delle interazioni.
SDK: Recensioni in Python, Recensioni in Node.