Avaliações

Cada endpoint de avaliações com cURL, Python e Node: fontes, configurações, lista, consolidação, detalhes, responder, editar, arquivar, frases e análises.

As avaliações são as notas em estrelas e os comentários que os clientes deixam no Google, Facebook e Yelp. A API armazena uma cópia de cada avaliação, permite que você responda e calcula análises das avaliações. Os caminhos REST usam reviews; as chaves das respostas e os títulos das páginas de referência usam interactions, o nome interno antigo do mesmo objeto. Este guia usa o termo avaliação em todo o texto. As operações de leitura exigem uma chave Read (leitura). Responder, editar, arquivar e alterar configurações exigem uma chave Write (escrita); uma operação de escrita com uma chave Read retorna 400 com SY90016.

Visão geral dos endpoints

Liste as fontes de avaliações permitidas pelo seu plano

GET /reviews/site-config retorna o catálogo de plataformas de avaliações às quais a conta tem direito. Ele não recebe parâmetros e seu escopo é a conta, portanto, armazene o resultado em cache em vez de chamá-lo para cada local. Os valores de siteUrl são os nomes de host aceitos por todos os outros filtros deste recurso.

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

Leia data.interactionSiteConfig[]. O exemplo usa uma conta do plano Launch; o conjunto exato depende do plano e do setor. Use siteUrl no filtro siteUrls dos endpoints de listagem e em siteUrls[].name ao editar as configurações.

Liste as fontes configuradas para um local

GET /locations/{locationId}/reviews/settings retorna uma entrada para cada plataforma compatível com o plano, com a URL de onde as avaliações são coletadas. Ele é a contraparte de leitura do endpoint de edição abaixo. O caminho aceita o id em base64 ou o número simples.

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

Leia data.interactionsSetting.siteSettings[]. Um valor não nulo de url significa que a plataforma está conectada e que as avaliações estão sendo coletadas daquela página. Um valor null em url significa que a plataforma está disponível, mas não está configurada. As entradas do Google e do Facebook são preenchidas automaticamente quando você conecta essas contas por OAuth e não podem ser sobrescritas pelo endpoint de edição. O Yelp precisa ser especificado explicitamente.

Edite as configurações de avaliações de um local

POST /locations/reviews/settings/edit define em quais fontes um local é monitorado e qual nota em estrelas conta como positiva. Os campos vão diretamente no corpo, sem um objeto input que os envolva. Adicionar uma fonte coloca uma coleta na fila, portanto, as avaliações do novo site chegam depois, não nesta resposta.

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

Leia data.editInteractionsSetting.interactionSetting.siteSettings[] para obter a seleção armazenada. monitored indica que a fonte está ativa; canRespond indica se respostas do proprietário podem ser publicadas nela pela API. Uma fonte rejeitada pela validação, como uma URL inacessível ou um site não incluído no plano, é retornada em errors com a configuração inalterada, portanto, verifique errors ao receber 200. Os SDKs lançam ValidationError nesse caso.

Listar avaliações de um local

GET /locations/{locationId}/reviews é uma conexão baseada em cursor em data.interactions, com as avaliações mais recentes primeiro. first tem o valor padrão de 20, portanto uma única chamada nunca retorna o histórico completo. Os filtros de array são strings JSON na string de consulta e devem ser codificados para URL; o exemplo de cURL usa -G com --data-urlencode para isso.

Além dos parâmetros opcionais category, categories e ratingFilter, que aceita um único valor, listados na página de referência.

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

Leia edges[].node. id é o que você passa ao responder, e canRespond indica se essa fonte aceita respostas do proprietário. totalCount é o número de correspondências em todo o conjunto de resultados, não nesta página. Pare a paginação quando hasNextPage for false ou quando uma página retornar edges vazio; um limite que coincida com a avaliação mais antiga é seguido por uma página vazia.

Percorrer todos os locais com a visão consolidada

GET /rollup_interactions é a mesma conexão baseada em cursor, abrangendo todos os locais aos quais a chave tem acesso, em data.rollupInteractions, com um locationId numérico em cada nó. Ela aceita os mesmos filtros que a lista por local. Não há filtro de local; um argumento locationIds é ignorado, não rejeitado. Nenhum dos 2 SDKs encapsula esse endpoint ainda, portanto os exemplos usam 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    }  }}

Agrupe os nós por locationId, o databaseId da loja. O pageInfo da visão consolidada pode omitir endCursor, portanto use o cursor da última edge como after; os 2 valores são equivalentes. Delimite as execuções agendadas com startDate e endDate em vez de reler o histórico, e respeite Retry-After ao receber um 429.

Buscar avaliações por ID

GET /reviewDetails retorna cópias atualizadas das avaliações armazenadas, sem paginação. A resposta é um array simples em data.interactionDetails.interactions, sem edges nem pageInfo, e cada avaliação inclui seu responses. Use-o para recarregar os dados de uma lista de acompanhamento e encontrar o responseId necessário para editar ou arquivar.

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 é o responseId para os endpoints de edição e arquivamento. Um ID de outra conta faz o endpoint retornar 200 com interactionDetails: null e um erro SY90001, portanto verifique se há null antes de acessar por índice.

Campos de avaliação e resposta

A referência de atributos é uma página exclusiva de documentação que lista todos os campos do objeto de avaliação e do objeto de resposta. Os campos que você mais usará:

Cada resposta em responses[] contém id, content, authorName, date, interactionStatus, editedResponse, respondedWith (ID do modelo) e remarks (detalhe da falha). interactionStatus passa por estes estados:

Publicar uma resposta do proprietário

POST /locations/reviews/respond publica uma resposta pública na plataforma de origem. Os campos vão diretamente no corpo da requisição. A resposta é aceita imediatamente e entregue de forma assíncrona, então interactionStatus começa em CREATED. Verifique canRespond na avaliação primeiro.

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

Guarde interaction.id: ele é o responseId usado para editar e arquivar. Uma resposta rejeitada retorna como 200 com errors preenchido dentro de data.respondToInteraction, então leia o corpo da resposta; os SDKs lançam ValidationError. Consulte novamente a avaliação pelo ID após uma breve espera para verificar se a resposta chegou a COMPLETED ou CONFIRMED.

Editar uma resposta

POST /locations/reviews/respond/edit altera o texto de uma resposta existente. A edição é reenviada à plataforma, então interactionStatus volta para CREATED e editedResponse passa a ser true assim que ela é aplicada. Prefira essa opção a arquivar e publicar novamente em plataformas que permitem uma única resposta.

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 é a string "true" quando a edição é aceita. Confirme o novo texto com uma chamada de consulta de detalhes e verifique o interactionStatus da resposta.

Arquivar uma resposta

POST /locations/reviews/respond/archive remove uma resposta de responses da avaliação que rastreamos em nosso sistema. É uma exclusão lógica: uma resposta já publicada no Google, Yelp ou Facebook permanece lá. Use essa opção para remover um rascunho que falhou ou foi substituído; use a edição para qualquer resposta publicada.

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

Após o arquivamento, o responseCount da avaliação diminui e responded reflete as respostas restantes.

Listar as frases que os clientes repetem

GET /review-phrases retorna um array simples em data.newReviewPhrases, com uma entrada por frase recorrente, cada uma com estatísticas calculadas apenas sobre as avaliações que contêm essa frase. Ele não é paginado; limite-o com phraseCount. Todos os filtros são opcionais e podem ser combinados, então ratingFilters=[1,2] com um startDate retorna as reclamações do último trimestre.

Além do parâmetro opcional categories e dos parâmetros obsoletos de valor único category e ratingFilter listados na página de referência.

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 é a frequência com que a frase aparece, overall-rating é a nota média dessas avaliações, delta é a variação percentual em relação ao período anterior e abs é a variação absoluta. Um 403 com SY90003 significa que a chave não pode ler um dos locais solicitados.

Consultar os KPIs de avaliações de um local

GET /locations/{locationId}/review-analytics-overview retorna quatro estatísticas em data.interactionsAnalyticsStats.stats. O intervalo de datas é opcional; ele restringe o período usado para calcular os valores e suas variações. Cada delta é a variação percentual em relação ao período anterior de mesma duração.

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

Uma conta nova sem período anterior informa um delta de 100, então não interprete as variações do primeiro mês como crescimento.

Obtenha a linha do tempo diária de avaliações

GET /locations/{locationId}/review-analytics-timeline retorna uma entrada por dia em data.interactionsChartData.data. Informe startDate e endDate sempre que o intervalo do gráfico for relevante; omitir esses parâmetros permite que o serviço escolha sua própria janela. Adicione site para exibir uma única origem separadamente.

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

Represente interactionCount como barras e averageRating como uma linha. A média corresponde apenas àquele dia, não é acumulada, e é null em um dia sem avaliações, então deixe uma lacuna em vez de representar zero.

Detalhe a análise de avaliações por origem

GET /locations/{locationId}/review-analytics-sites-stats retorna uma entrada por origem de avaliações em data.interactionsSitesStats.stats. Use-o para identificar qual plataforma alterou a média.

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 contêm, cada um, um value e um delta; baseRating e baseInteractions são os valores no início do período a partir do qual a variação é medida. recency é a data e hora da avaliação mais recente, ou null quando a origem nunca retornou uma avaliação. Um newInteractions de 0 com um recency de meses atrás geralmente significa que a conexão com a origem ficou desatualizada, então verifique as origens do local.

Erros que você verá

As operações de escrita também podem retornar 200 com errors preenchido dentro de data.<op>, então leia o corpo da resposta de cada operação de escrita. A lista completa está em Códigos de erro.

Próximos passos

• Busque avaliações: crie uma fila de pendências e receba notificações por webhook.
• Responda a avaliações: responda, confirme, edite, arquive.
• Análise de avaliações: quadro de indicadores, gráfico, painel de reclamações, registros diários.
• Análise: métricas dos perfis do Google, Facebook e Bing para o mesmo local.
• Página inicial da referência: Avaliações. SDKs: Avaliações em Python, Avaliações em Node.