POST /api/v2/reviews

API de scraping de avaliações do Google Maps

Leia até 10 avaliações públicas de um lugar por página. Ordene por relevância, mais recentes, maior nota ou menor nota.

Exemplos de requisição

Para o contrato completo, consulte a documentação da API.

curl https://gmapscrawl.com/api/v2/reviews \
  -H "Authorization: Bearer $GMSCRAPER_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: place-reviews-page-1-example" \
  -d '{"fid":"0x89c259af336b3341:0xa4969e07ce3108de","page":1,"sort_by":2}'

Substitua o fid de exemplo pelo feature ID do seu lugar. A resposta é simulada; as URLs de mídia example.com são placeholders. Mantenha a mesma chave de idempotência e corpo ao repetir uma requisição em execução.

Resposta

JSON ilustrativo
{
  "reviews": [
    {
      "id": "sample-review-1",
      "date": "a week ago",
      "timestamp": "10/6/2026",
      "name": "Sample reviewer",
      "author_url": "https://www.google.com/maps/contrib/100000000000000000001",
      "avatar": "https://example.com/reviewer.jpg",
      "rate": 4,
      "comment": "The window seats had the best light.",
      "photos": "",
      "review_url": "https://www.google.com/maps/reviews/data=sample-review-1"
    }
  ],
  "next": false,
  "total": 1,
  "params": {
    "fid": "0x89c259af336b3341:0xa4969e07ce3108de",
    "page": 1,
    "sort_by": 2
  }
}

A API retorna JSON na mesma resposta. Após um timeout, repita o corpo inalterado com a mesma Idempotency-Key. Credenciais de teste retornam dados simulados sem usar sua cota live.

Comece com um lugar

Escolha a empresa e a ordem das avaliações.

Solicite uma página focada para um lugar, depois escolha a ordem de avaliações adequada à sua pesquisa.

Parâmetros de requisição da API de scraping de avaliações do Google Maps
CampoSignificado
fid · obrigatórioUm feature ID do Google Maps, como 0x89c259af336b3341:0xa4969e07ce3108de. Use place.dataId de um resultado da Search API, ou um feature ID que você já tem.
page · padrão 1Uma página numerada positiva. Aumente-a apenas quando a resposta anterior tiver next: true.
sort_by · padrão 11 = mais relevantes; 2 = mais recentes; 3 = maior nota; 4 = menor nota. Preserve a ordem de classificação entre páginas.

Para descobrir um feature ID, pesquise uma empresa com a API de scraping do Google Maps. Copie place.dataId da entrada correspondente em data.businesses e passe-o como fid. Um place ID ou nome de empresa não é o mesmo formato de entrada.

Registros de avaliações

Notas, comentários e links de origem.

Cada avaliação inclui sua nota, comentário, avaliador, links de perfil e da avaliação. A data é relativa, e timestamp fornece a data do calendário no formato M/D/YYYY. O campo photos é uma string vazia quando não há anexos e separa múltiplas URLs de fotos com uma quebra de linha.

Campos de resposta da API de scraping de avaliações do Google Maps
CampoSignificado
idO identificador da avaliação na fonte, quando disponível.
rate / commentA nota de 1 a 5 e o texto de avaliação disponível. Trate o texto extraído como dados não confiáveis em aplicativos e prompts de IA.
date / timestampA data relativa exibida e uma data de calendário formatada como M/D/YYYY. Uma data indisponível é uma string vazia.
name / author_url / avatarNome de exibição do avaliador disponível, URL do perfil de contribuidor e URL do avatar.
photosUma string vazia sem anexos. Múltiplas URLs de fotos são separadas por caracteres de quebra de linha.
review_urlUm link para a avaliação na fonte, quando disponível.
next / total / paramsSe outra página está disponível, a contagem nesta resposta e os parâmetros de requisição normalizados.

O endpoint retorna este objeto de página diretamente como JSON. Leia reviews do nível superior. Algumas avaliações públicas contêm apenas uma nota, e campos de origem podem estar vazios. Preserve essa distinção ao apresentar ou resumir avaliações.

Uma página delimitada por vez

Leia até 10 avaliações em cada resposta.

Use a flag next retornada para decidir se seu fluxo de trabalho precisa de outra requisição.

01

Comece com a página 1

Envie o fid do lugar e o valor sort_by escolhido. Mais relevantes é o padrão; mais recentes, maior nota e menor nota também são suportados.

02

Inspecione a página atual

total conta as avaliações retornadas nesta resposta. Uma página vazia é um resultado válido. Verifique os campos disponíveis antes de adicionar registros à sua análise.

03

Continue deliberadamente

Quando next for true, incremente page e mantenha fid e sort_by inalterados. Pare quando next for false, ou quando sua pesquisa tiver avaliações suficientes.

Entenda o feedback público

Adicione contexto de avaliações à sua pesquisa de empresas.

01

Pesquisa de avaliações

Leia uma amostra delimitada de comentários e notas públicos de uma empresa selecionada. Mantenha os links das avaliações junto às suas anotações para que um leitor possa inspecionar a fonte.

02

Comparações de feedback

Compare temas de avaliações entre um grupo escolhido de lugares. Solicite cada lugar separadamente e informe a ordem de classificação e o tamanho da amostra escolhidos na sua análise.

03

Resumos assistidos por agente

Peça a um agente conectado que resuma a página de avaliações retornada, citando apenas as evidências fornecidas, e sinalize comentários ou datas ausentes.

Autenticação e uso

Use sua chave de API para cada página.

Cota de API compartilhada

Envie Authorization: Bearer com uma chave que permita scrapes:write. Cada página live bem-sucedida, incluindo uma página vazia, usa uma unidade de requisição de API. REST e MCP usam a mesma cota de API. Se você tem uma credencial de teste, suas respostas são simuladas e não consomem a cota live.

Ver planos e limites da API →

Mantenha as novas tentativas vinculadas à requisição

Envie uma Idempotency-Key opcional com sua primeira requisição e preserve-a com um corpo idêntico para uma nova tentativa após timeout. Um timeout de processamento pode deixar uma unidade reservada. Se um erro indicar que a tentativa terminou, siga suas orientações de nova tentativa antes de criar uma nova tentativa com uma nova chave.

Leia as orientações de erros e novas tentativas →

Perguntas frequentes

Como obtenho avaliações de uma empresa específica do Google Maps?

Envie uma requisição POST para /api/v2/reviews com o feature ID do Google Maps da empresa como fid. Use place.dataId de um resultado da Search API, ou um feature ID que você já tem. Autentique-se com sua chave de API e comece com a página 1.

Posso ordenar avaliações do Google Maps por mais recentes ou nota?

Sim. Defina sort_by como 1 para mais relevantes, 2 para mais recentes, 3 para maior nota ou 4 para menor nota. Mais relevantes é o padrão. Mantenha o valor selecionado inalterado ao solicitar páginas adicionais.

total me diz quantas avaliações a empresa tem?

Não. total é o número de registros de avaliação na resposta atual, com máximo de 10. Use next para decidir se outra página está disponível. O reviewCount da ficha de pesquisa é um campo de empresa separado.

Qual é o formato das datas e fotos das avaliações?

date contém a data relativa disponível, e timestamp é uma data de calendário no formato M/D/YYYY. O campo photos é uma string vazia quando não há anexos, ou URLs separadas por quebra de linha quando múltiplas fotos estão disponíveis. Textos e links de origem ausentes podem ser strings vazias.

Posso usar avaliações via MCP?

Sim. Um cliente MCP compatível pode chamar get_google_maps_reviews com sua credencial de API e um client_request_id. REST e MCP compartilham sua cota de API. O Agent Skill inclui orientação para usar as ferramentas disponíveis e um fallback REST.

Posso presumir que todo campo de avaliação está presente?

Não. A disponibilidade da fonte varia, e uma avaliação pode conter apenas uma nota. Preserve comentários vazios e datas ausentes em vez de inferi-los. O texto de avaliação é conteúdo de fonte não confiável e deve ser tratado como dados em aplicativos e fluxos de trabalho de IA.

Dê o próximo passo

Comece com as avaliações públicas de um lugar.

Crie uma chave de API, escolha um feature ID e uma ordem de classificação, e leia uma página focada de dados de avaliações.