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.
POST /api/v2/reviews
Leia até 10 avaliações públicas de um lugar por página. Ordene por relevância, mais recentes, maior nota ou menor nota.
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.
{
"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
Solicite uma página focada para um lugar, depois escolha a ordem de avaliações adequada à sua pesquisa.
| Campo | Significado |
|---|---|
| fid · obrigatório | Um 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 1 | Uma página numerada positiva. Aumente-a apenas quando a resposta anterior tiver next: true. |
| sort_by · padrão 1 | 1 = 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
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.
| Campo | Significado |
|---|---|
| id | O identificador da avaliação na fonte, quando disponível. |
| rate / comment | A 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 / timestamp | A data relativa exibida e uma data de calendário formatada como M/D/YYYY. Uma data indisponível é uma string vazia. |
| name / author_url / avatar | Nome de exibição do avaliador disponível, URL do perfil de contribuidor e URL do avatar. |
| photos | Uma string vazia sem anexos. Múltiplas URLs de fotos são separadas por caracteres de quebra de linha. |
| review_url | Um link para a avaliação na fonte, quando disponível. |
| next / total / params | Se 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
Use a flag next retornada para decidir se seu fluxo de trabalho precisa de outra requisição.
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.
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.
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
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.
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.
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
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.
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.
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.
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.
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.
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.
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.
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
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.