Avaliações

Busque avaliações, responda a elas e analise-as com o SDK listingsapi-js.

Avaliações (chamadas de "interactions" na API) são notas em estrelas e comentários em texto livre coletados do Google, Facebook e Yelp. Todos os métodos de avaliação estão na instância de cliente ListingsAPI. Operações de escrita que falham no servidor lançam uma exceção ValidationError, portanto você nunca precisa verificar os indicadores success nos valores retornados.

fetchInteractions

Busque avaliações de um local com filtros opcionais e paginação baseada em cursor. Os IDs numéricos dos locais são codificados automaticamente.

TypeScript

// Single pageconst result = await client.fetchInteractions(16808, {first:         25,startDate:     '2026-01-01',endDate:       '2026-06-30',ratingFilters: [1, 2],}); if (!Array.isArray(result)) {console.log(result.interactions);   // Interaction[]console.log(result.totalCount);     // number | undefinedconsole.log(result.pageInfo);       // { hasNextPage, hasPreviousPage, startCursor, endCursor }} // All reviews at once, returns a flat Interaction[]const all = await client.fetchInteractions(16808, {fetchAll:  true,startDate: '2026-01-01',});

Opções

Parâmetro	Tipo	Descrição
`first`	`number`	Tamanho da página na paginação para frente.
`after`	`string`	Cursor de um `pageInfo.endCursor` anterior.
`before`	`string`	Cursor para paginação para trás.
`last`	`number`	Tamanho da página na paginação para trás.
`fetchAll`	`boolean`	Percorra as páginas automaticamente e retorne um `Interaction[]` sem aninhamento.
`pageSize`	`number`	Tamanho da página usado internamente quando `fetchAll` é `true` (padrão: `100`).
`startDate`	`string`	Limite inferior, `YYYY-MM-DD`.
`endDate`	`string`	Limite superior, `YYYY-MM-DD`.
`category`	`string`	Filtro por categoria de interação.
`siteUrls`	`string[]`	Restrinja a diretórios específicos, e.g. `['maps.google.com']`.
`ratingFilters`	`number[]`	Notas em estrelas a manter, e.g. `[1, 2]`.

Retorno

Sem fetchAll, um objeto InteractionResponse: success, interactions (Interaction[]), pageInfo (hasNextPage, hasPreviousPage, startCursor, endCursor), totalCount quando a API o informa, e raw (o payload sem processamento). Com fetchAll: true, um Interaction[] sem aninhamento. Cada Interaction contém id, content, rating, siteName, siteUrl, reviewerName, publishedAt, category e responses.

fetchReviewDetails

Busque informações detalhadas sobre avaliações específicas pelo ID da interação. Um array de entrada vazio retorna imediatamente um objeto vazio, sem uma chamada de rede.

TypeScript

const details = await client.fetchReviewDetails(['interaction-uuid-1','interaction-uuid-2',]);

respondToReview

Publique uma resposta a uma avaliação. O envio ao diretório de origem é assíncrono.

TypeScript

await client.respondToReview('interaction-uuid','Thank you for the feedback! We hope to see you again soon.',);

Parâmetro	Tipo	Descrição
`interactionId`	`string`	O ID da interação da avaliação.
`responseContent`	`string`	Texto da resposta a publicar.

editReviewResponse

Edite uma resposta existente.

TypeScript

await client.editReviewResponse('review-uuid','response-uuid','Updated response text.',);

Parâmetro	Tipo	Descrição
`reviewId`	`string`	A avaliação à qual a resposta pertence.
`responseId`	`string`	A resposta a editar.
`responseContent`	`string`	Novo texto da resposta.

archiveReviewResponse

Arquive (oculte) uma resposta.

TypeScript

await client.archiveReviewResponse('response-uuid');

Análise de avaliações

Os três métodos de análise recebem um ID de local e um intervalo opcional de { startDate, endDate } (YYYY-MM-DD) e retornam um objeto ReviewAnalytics cuja estrutura varia conforme o endpoint.

fetchReviewAnalyticsOverview

Estatísticas gerais de um intervalo de datas: dados agregados de notas e volume de avaliações do local.

TypeScript

const overview = await client.fetchReviewAnalyticsOverview(16808, {startDate: '2026-01-01',endDate:   '2026-06-30',});console.log(overview);

fetchReviewAnalyticsTimeline

Contagens de avaliações e notas ao longo do tempo, adequadas para criar gráficos.

TypeScript

const timeline = await client.fetchReviewAnalyticsTimeline(16808, {startDate: '2026-01-01',endDate:   '2026-06-30',});

fetchReviewAnalyticsSitesStats

Distribuição das avaliações por site de origem (Google, Facebook, Yelp).

TypeScript

const siteStats = await client.fetchReviewAnalyticsSitesStats(16808, {startDate: '2026-01-01',endDate:   '2026-06-30',});

fetchReviewPhrases

Análise de frases e sentimentos em um ou mais locais durante um intervalo de datas. Recebe um único objeto de opções; locationIds é obrigatório e uma lista vazia retorna [] sem uma chamada de rede.

TypeScript

const phrases = await client.fetchReviewPhrases({locationIds: ['TG9jYXRpb246MTY4MDg=', 'TG9jYXRpb246MTY4MDk='],startDate:   '2026-01-01',endDate:     '2026-06-30',siteUrls:    ['maps.google.com'],}); for (const p of phrases) {console.log(p.phrase, p.count, p.sentiment);}

Opções

Parâmetro	Tipo	Obrigatório	Descrição
`locationIds`	`string[]`	Sim	IDs de locais codificados em Base64.
`startDate`	`string`	Não	Limite inferior, `YYYY-MM-DD`.
`endDate`	`string`	Não	Limite superior, `YYYY-MM-DD`.
`siteUrls`	`string[]`	Não	Restrinja a diretórios específicos.

Configurações de avaliações

fetchReviewSettings

Obtenha as configurações das fontes de avaliações de um local.

TypeScript

const settings = await client.fetchReviewSettings(16808);console.log(settings);

editReviewSettings

Defina ou atualize as URLs das fontes de avaliações monitoradas para um local. Cada entrada é um ReviewSiteUrl com um name e um url.

TypeScript

await client.editReviewSettings(16808, [{ name: 'Google', url: 'https://www.google.com/maps/place/acme-dental' },{ name: 'Yelp',   url: 'https://www.yelp.com/biz/acme-dental-new-york' },]);

Parâmetro	Tipo	Descrição
`locationId`	`string \| number`	Os IDs numéricos são codificados automaticamente.
`siteUrls`	`ReviewSiteUrl[]`	Entradas de `{ name, url }` por fonte de avaliações.

fetchReviewSiteConfig

Obtenha a lista de fontes de avaliações elegíveis de toda a conta. Não recebe argumentos e retorna um ReviewSiteConfig[].

TypeScript

const config = await client.fetchReviewSiteConfig();

Locais: consulte IDs de locais
Análises: análises de perfis no Google, Bing e Facebook
Casos de uso: exemplos práticos de monitoramento de avaliações e envio de respostas em massa