Busque avaliações de um local ou de toda a sua conta

Liste avaliações mais recentes de um local, filtre notas baixas sem resposta, pagine com cursores, consulte toda a conta e receba avisos por webhook.

As avaliações são chamadas de interactions na API. Todas as avaliações do Google, Facebook ou Yelp são retornadas em uma lista por local e em uma visão consolidada da conta, de modo que uma única integração abrange todas as fontes que você conecta.

1. Liste as avaliações mais recentes de um local

GET /locations/{locationId}/reviews é uma conexão baseada em cursores em data.interactions. Os resultados vêm dos mais recentes para os mais antigos, e o valor padrão de first é 20, portanto uma única chamada nunca representa o histórico completo. O caminho aceita o id em base64 ou o número simples.

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

Leia data.interactions.edges[].node. O id é um UUID simples, não um id Relay em base64, e é o que você passa ao responder. totalCount é o número de correspondências em todo o conjunto de resultados, não nesta página. canRespond indica se essa fonte aceita respostas do proprietário pela API.

2. Filtre as avaliações de baixa pontuação sem resposta

Os filtros de array são strings JSON na string de consulta: ratingFilters=[1,2] mantém as avaliações de 1 e 2 estrelas, e responseStatus=["PENDING"] mantém as avaliações sem resposta do proprietário. Os colchetes e as aspas devem ser codificados para URL, por isso o exemplo de cURL usa -G com --data-urlencode, que codifica cada valor e o acrescenta à URL para você. A string de consulta literal 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'

Os filtros que você pode combinar:

Parâmetro	Valores	Observações
`siteUrls`	`["maps.google.com"]`, `["facebook.com"]`, `["yelp.com"]`	Nomes de host obtidos em Liste as fontes de avaliações de uma conta.
`ratingFilters`	`[1,2]` e assim por diante	Pontuações em estrelas a manter.
`responseStatus`	`["PENDING"]` ou `["RESPONDED"]`	Se existe uma resposta do proprietário.
`sortOrder`	`["NEWEST_FIRST"]`, `["OLDEST_FIRST"]`, `["LAST_RESPONDED"]`	A ordem padrão é dos mais recentes para os mais antigos.
`startDate`, `endDate`	`YYYY-MM-DD`	Strings simples, não JSON.
`searchString`	texto livre	Pesquisa de texto completo no corpo da avaliação.

3. Percorra as páginas com cursores

Passe pageInfo.endCursor de volta como after. Pare quando hasNextPage for false ou quando uma página retornar um array edges vazio; quando o limite da página coincide com a avaliação mais antiga, a página seguinte é vazia. Ambos os SDKs podem ler as páginas para você.

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

Cada requisição conta para o seu limite de requisições, e consultar um local com 425 avaliações usando first=50 exige 9 chamadas. Ao receber 429, aguarde Retry-After antes de buscar a próxima página. Para uma sincronização agendada, delimite a execução com startDate e endDate em vez de reler o histórico. Consulte Limites de requisições.

4. Consulte toda a conta com a visão consolidada

GET /rollup_interactions retorna os mesmos nós de todos os locais que a chave pode acessar, em data.rollupInteractions, com um locationId em cada nó. Ele aceita os mesmos filtros, além de tag, cujo valor padrão é all. Não há filtro por local; faça o agrupamento por locationId. Nenhum dos SDKs oferece um método para esse endpoint ainda, por isso os exemplos dos SDKs o chamam com 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'

Cada nó tem a mesma estrutura da etapa 1, além de um locationId numérico, o databaseId da loja. O pageInfo da visão consolidada pode omitir endCursor, por isso use o cursor da última aresta como after; os dois valores são equivalentes.

5. Busque os detalhes completos por id

Quando você tem ids armazenados, GET /reviewDetails retorna cópias atualizadas sem paginação. interactionIds é um array JSON, codificado para URL como os outros filtros. A resposta é um array simples em data.interactionDetails.interactions, e cada interação inclui seu 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"            }          ]        }      ]    }  }}

Um id de outra conta retorna 200 com interactionDetails: null e um erro SY90001, por isso verifique se há null antes de acessar por índice.

6. Receba eventos de webhook em vez de fazer consultas periódicas

Com uma URL de webhooks configurada, um evento interaction.review é disparado quando uma avaliação é ingerida ou alterada. Os campos da avaliação ficam em data.interaction, não diretamente em data, e data.interaction.id é o mesmo UUID retornado pela lista.

Dois cuidados. location_id neste evento é repassado sem normalização: pode ser uma string numérica ou null, então faça a conversão em vez de confiar no tipo. E o mesmo id chega novamente sempre que a avaliação muda, então trate o evento como um sinal para reler a avaliação, não como uma inserção única. A entrega ocorre em uma única tentativa, sem novas tentativas, então mantenha uma varredura periódica da etapa 4 como garantia. A configuração está em Reaja a eventos com webhooks.

Próximos passos

Responda a avaliações: responda às avaliações pendentes que você acabou de encontrar e, em seguida, edite ou arquive a resposta.
Análise de avaliações: nota, volume e taxa de resposta para o mesmo local.
Referência: Liste interações, Obtenha interações agregadas, Obtenha interações por IDs, Atributos de interação.
SDKs: Avaliações em Python, Avaliações em Node.