Recensioni

Tutti gli endpoint recensioni, esempi cURL/Python/Node: fonti, impostazioni, elenco, riepilogo, dettagli, risposte, modifiche, archivio, frasi e analisi.

Le recensioni sono le valutazioni in stelle e i commenti che i clienti lasciano su Google, Facebook e Yelp. L'API ne memorizza una copia ciascuna, ti permette di rispondere e calcola le analisi delle recensioni. I percorsi REST usano reviews; le chiavi delle risposte e i titoli delle pagine di riferimento usano interactions, il precedente nome interno dello stesso oggetto. Questa guida usa sempre il termine recensione. Le operazioni di lettura richiedono una chiave Read (lettura). Per rispondere, modificare, archiviare e cambiare le impostazioni serve una chiave Write (scrittura); l'uso di una chiave Read per un'operazione di scrittura restituisce 400 con SY90016.

Panoramica degli endpoint

Elenca le fonti delle recensioni consentite dal tuo piano

GET /reviews/site-config restituisce il catalogo delle piattaforme di recensioni a cui l'account ha diritto di accedere. Non accetta parametri e opera a livello di account, quindi memorizza il risultato nella cache invece di chiamarlo per ogni sede. I valori di siteUrl sono i nomi host accettati da tutti gli altri filtri di questa risorsa.

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

Leggi data.interactionSiteConfig[]. L'esempio riguarda un account con piano Launch; l'insieme esatto dipende dal piano e dal settore. Usa siteUrl per il filtro siteUrls degli endpoint di elenco e per siteUrls[].name quando modifichi le impostazioni.

Elenca le fonti configurate per una sede

GET /locations/{locationId}/reviews/settings restituisce una voce per ogni piattaforma supportata dal piano, con l'URL da cui vengono recuperate le recensioni. È la controparte di lettura dell'endpoint di modifica descritto di seguito. Il percorso accetta l'id in base64 o il semplice numero.

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

Leggi data.interactionsSetting.siteSettings[]. Un valore non nullo per url indica che la piattaforma è collegata e che le recensioni vengono recuperate da quella pagina. Un valore null per url indica che la piattaforma è disponibile ma non configurata. Le voci di Google e Facebook vengono compilate automaticamente quando colleghi questi account tramite OAuth e non possono essere sovrascritte dall'endpoint di modifica. Yelp deve essere specificato esplicitamente.

Modifica le impostazioni delle recensioni di una sede

POST /locations/reviews/settings/edit imposta le fonti su cui viene monitorata una sede e la valutazione in stelle a partire dalla quale una recensione è considerata positiva. I campi vanno direttamente nel corpo, non in un contenitore input. L'aggiunta di una fonte mette in coda un'operazione di scraping, quindi le recensioni del nuovo sito arrivano in seguito, non in questa risposta.

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

Leggi data.editInteractionsSetting.interactionSetting.siteSettings[] per ottenere la selezione memorizzata. monitored indica che la fonte è attiva; canRespond indica se è possibile pubblicarvi risposte del proprietario tramite l'API. Una fonte rifiutata dalla convalida, ad esempio un URL irraggiungibile o un sito non incluso nel piano, viene restituita in errors lasciando invariata l'impostazione, quindi controlla errors quando ricevi 200. In questo caso gli SDK sollevano ValidationError.

Elenca le recensioni di una sede

GET /locations/{locationId}/reviews è una connessione a cursore disponibile su data.interactions, con le recensioni più recenti per prime. first ha un valore predefinito di 20, quindi una singola chiamata non restituisce mai l'intera cronologia. I filtri array sono stringhe JSON nella stringa di query e devono essere codificati per l'URL; l'esempio cURL usa -G con --data-urlencode a questo scopo.

Sono disponibili anche i parametri facoltativi category, categories e ratingFilter a valore singolo, elencati nella pagina di riferimento.

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

Leggi edges[].node. id è il valore che passi quando rispondi, mentre canRespond indica se quella fonte accetta risposte del proprietario. totalCount è il numero di corrispondenze nell'intero insieme di risultati, non in questa pagina. Interrompi la paginazione quando hasNextPage è false o quando una pagina restituisce edges vuoto; se il limite della pagina coincide con la recensione più vecchia, segue una pagina vuota.

Passa in rassegna tutte le sedi con l'aggregazione

GET /rollup_interactions è la stessa connessione a cursore, estesa a tutte le sedi visibili alla chiave e disponibile su data.rollupInteractions, con un locationId numerico su ciascun nodo. Accetta gli stessi filtri dell'elenco per singola sede. Non esiste un filtro per sede; un argomento locationIds viene ignorato, non rifiutato. Nessuno dei due SDK fornisce ancora un wrapper per questo endpoint, quindi gli esempi usano requests e 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    }  }}

Raggruppa i nodi per locationId, il databaseId del negozio. Il pageInfo dell'aggregazione può omettere endCursor, quindi usa il cursor dell'ultimo edge come after; i due valori sono equivalenti. Delimita le esecuzioni pianificate con startDate e endDate invece di rileggere la cronologia e rispetta Retry-After quando ricevi un 429.

Recupera le recensioni per ID

GET /reviewDetails restituisce copie aggiornate delle recensioni memorizzate senza paginazione. La risposta è un semplice array in data.interactionDetails.interactions, senza edges o pageInfo, e ogni recensione include il proprio responses. Usalo per ricaricare i dati di un elenco di monitoraggio e per trovare il responseId necessario per la modifica o l'archiviazione.

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 è il responseId per gli endpoint di modifica e archiviazione. Con un ID di un altro account, viene restituito 200 con interactionDetails: null e un errore SY90001, quindi verifica la presenza di null prima di accedere agli elementi tramite indice.

Campi delle recensioni e delle risposte

La guida di riferimento degli attributi è una pagina di sola documentazione che elenca tutti i campi dell'oggetto recensione e dell'oggetto risposta. I campi che userai più spesso:

Ogni risposta in responses[] contiene id, content, authorName, date, interactionStatus, editedResponse, respondedWith (ID del modello) e remarks (dettaglio dell'errore). interactionStatus passa attraverso questi stati:

Pubblica una risposta del proprietario

POST /locations/reviews/respond pubblica una risposta pubblica sulla piattaforma di origine. I campi vanno direttamente nel body. La risposta viene accettata immediatamente e inviata in modo asincrono, quindi interactionStatus parte da CREATED. Controlla prima canRespond nella recensione.

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

Conserva interaction.id: è il valore responseId da usare per la modifica e l'archiviazione. Una risposta rifiutata viene restituita come 200 con errors valorizzato all'interno di data.respondToInteraction, quindi leggi il body; gli SDK generano ValidationError. Recupera nuovamente la recensione tramite ID dopo una breve attesa per verificare che la risposta raggiunga COMPLETED o CONFIRMED.

Modifica una risposta

POST /locations/reviews/respond/edit modifica il testo di una risposta esistente. La modifica viene inviata nuovamente alla piattaforma, quindi interactionStatus torna a CREATED e editedResponse diventa true una volta applicata. Preferisci questa operazione all'archiviazione e alla ripubblicazione sulle piattaforme che consentono una sola risposta.

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 è la stringa "true" quando la modifica viene accettata. Conferma il nuovo testo con una chiamata ai dettagli e controlla interactionStatus della risposta.

Archivia una risposta

POST /locations/reviews/respond/archive rimuove una risposta da responses della recensione che monitoriamo nel nostro sistema. È un'eliminazione logica: una risposta già pubblicata su Google, Yelp o Facebook rimane lì. Usa questa operazione per rimuovere una bozza il cui invio non è riuscito o che è stata sostituita; usa la modifica per qualsiasi risposta pubblicata.

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

Dopo l'archiviazione, responseCount della recensione diminuisce e responded riflette le risposte rimanenti.

Elenca le espressioni che i clienti ripetono

GET /review-phrases restituisce un semplice array in data.newReviewPhrases, con una voce per ogni espressione ricorrente e statistiche calcolate solo sulle recensioni che la contengono. Non è paginato; limitane le dimensioni con phraseCount. Tutti i filtri sono facoltativi e combinabili, quindi ratingFilters=[1,2] insieme a startDate restituisce le lamentele dell'ultimo trimestre.

Inoltre, sono disponibili il parametro facoltativo categories e i parametri deprecati a valore singolo category e ratingFilter elencati nella pagina di riferimento.

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 indica quante volte compare l'espressione, overall-rating è la valutazione media di quelle recensioni, delta è la variazione percentuale rispetto al periodo precedente e abs è la variazione assoluta. Un 403 con SY90003 indica che la chiave non può leggere una delle sedi richieste.

Leggi i KPI delle recensioni per una sede

GET /locations/{locationId}/review-analytics-overview restituisce quattro statistiche in data.interactionsAnalyticsStats.stats. L'intervallo di date è facoltativo; restringe il periodo su cui vengono calcolati i valori e le relative variazioni. Ogni delta è la variazione percentuale rispetto al periodo precedente della stessa durata.

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

Un account appena creato senza un periodo precedente riporta un valore delta pari a 100, quindi non interpretare le variazioni del primo mese come crescita.

Recupera la cronologia giornaliera delle recensioni

GET /locations/{locationId}/review-analytics-timeline restituisce una voce per giorno in data.interactionsChartData.data. Passa startDate e endDate ogni volta che l'intervallo del grafico è importante; se li ometti, il servizio sceglie autonomamente la finestra temporale. Aggiungi site per rappresentare una singola fonte separatamente.

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

Rappresenta interactionCount con barre e averageRating con una linea. La media si riferisce solo a quel giorno, non è una media progressiva, ed è null nei giorni senza recensioni, quindi lascia un'interruzione anziché rappresentare uno zero.

Suddividi le analisi delle recensioni per fonte

GET /locations/{locationId}/review-analytics-sites-stats restituisce una voce per fonte delle recensioni in data.interactionsSitesStats.stats. Usalo per individuare quale piattaforma ha fatto variare la media.

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 e newInteractions contengono ciascuno un value e un delta; baseRating e baseInteractions sono i valori all'inizio del periodo rispetto ai quali viene misurato il delta. recency è il timestamp della recensione più recente, null quando la fonte non ne ha mai restituita una. Un newInteractions pari a 0 con un recency risalente a mesi fa indica in genere che la connessione alla fonte non è più aggiornata, quindi controlla le fonti della sede.

Errori che incontrerai

Le operazioni di scrittura possono anche restituire 200 con errors valorizzato all'interno di data.<op>, quindi leggi il corpo della risposta di ogni operazione di scrittura. L'elenco completo è in Codici di errore.

Passaggi successivi

• Recupera le recensioni: crea una coda di recensioni in attesa e ricevi notifiche tramite webhook.
• Rispondi alle recensioni: rispondi, conferma, modifica, archivia.
• Analisi delle recensioni: scheda riepilogativa, grafico, pannello dei reclami, istantanee giornaliere.
• Analisi: metriche dei profili Google, Facebook e Bing per la stessa sede.
• Pagina di riferimento: Recensioni. SDK: Recensioni in Python, Recensioni in Node.