POST /api/v1/search

API de scraping do Google Maps

Encontre empresas por palavra-chave e localização. Receba até 20 registros estruturados de empresas na mesma resposta JSON, prontos para seu aplicativo ou fluxo de pesquisa.

Exemplos de requisição

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

curl https://gmapscrawl.com/api/v1/search \
  -H "Authorization: Bearer $GMSCRAPER_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: seattle-coffee-search-001" \
  -d '{"q":"coffee shops in Seattle","page":1,"extra":false}'

Resposta vazia ilustrativa. Uma pesquisa live retorna as empresas disponíveis. Mantenha sua chave de API no lado do servidor; use uma nova chave de idempotência para novo trabalho e preserve-a para uma nova tentativa inalterada.

Resposta

JSON ilustrativo
{
  "data": {
    "total": 0,
    "params": {
      "q": "coffee shops in Seattle",
      "page": 1,
      "hl": "en",
      "extra": false
    },
    "businesses": []
  },
  "request_id": "req_example",
  "schema_version": "2026-09-22"
}

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.

Dados estruturados de empresas

De uma pesquisa no Maps a registros que você pode usar.

Leia data.businesses da resposta. Cada empresa agrupa seus campos de ficha sob place; a disponibilidade dos campos depende da fonte.

01

Identidade e localização da empresa

Use o nome da empresa, categorias, endereço formatado, coordenadas e URL do Maps para organizar um dataset de empresas locais.

02

Contato e reputação

Leia telefones, sites, avaliações e contagens de avaliações disponíveis. Com extra ativado, solicite enriquecimento de contato por e-mail e redes sociais.

03

Identificadores e datas de observação

Guarde place.dataId para consultas de avaliações e fotos. Inspecione place.observedAt e contactsCheckedAt para entender quando os dados foram observados.

Mantenha visíveis os dados ausentes e antigos

Campos indisponíveis podem ser null ou vazios, e o enriquecimento pode relatar not_found ou failed. Um registro não garante que um endereço de e-mail ou site exista. Detalhes do Maps podem ser reutilizados por até 730 dias com seus timestamps de observação originais; avalie a atualidade antes de usar um registro.

Leia sobre atualidade dos dados →

Uma requisição focada

Escolha a consulta, a página e o enriquecimento.

Envie um corpo JSON com sua chave de API do lado do servidor no cabeçalho de autorização. Apenas q é obrigatório.

Parâmetros da Google Maps Search API
ParâmetroRequisitoFinalidade
qObrigatórioUma palavra-chave de empresa e localização, como cafeterias em Seattle. Use de 2 a 200 caracteres.
pagePadrão: 1Uma página de pesquisa numerada de 1 a 10. Cada requisição retorna no máximo 20 empresas.
llOpcionalUm viewport do Maps no formato @47.6062,-122.3321,12z para orientar a localização da pesquisa.
hlPadrão: enO código de idioma usado para a pesquisa.
glOpcionalUm código de país de duas letras que qualifica a consulta. Não é um filtro geográfico estrito.
extraPadrão: falseDefina true para solicitar o enriquecimento de contato por e-mail e redes sociais disponível. Isso pode demorar mais.

A resposta ecoa os parâmetros normalizados em data.params. O valor data.total conta as empresas nesta resposta, e não o número total de empresas no Google Maps. Escolha outra página explicitamente quando seu fluxo de trabalho precisar de mais resultados.

Construa sua primeira integração

Uma requisição. Um próximo passo útil.

A Search API é síncrona: leia o resultado diretamente da resposta HTTP.

01

Crie sua chave de API

Use seu workspace de API para criar uma chave com a permissão scrapes:write. Armazene a chave no ambiente do seu servidor e envie Authorization: Bearer com a requisição.

Abrir chaves de API
02

Pesquise uma área delimitada

Escolha uma categoria e localização, solicite a página 1 e inspecione os campos de ficha retornados. Para uma comparação de mercado, faça pesquisas separadas para as áreas que deseja comparar.

03

Siga um identificador de lugar

Use place.dataId de uma empresa correspondente como fid para recuperar uma página de avaliações ou de galeria. São requisições separadas com seus próprios registros retornados.

Explorar a Reviews API

Planeje para requisições reais

Páginas previsíveis, limites explícitos.

Uso e disponibilidade

Cada página de pesquisa live bem-sucedida usa uma unidade de requisição de API, incluindo um resultado vazio. REST e MCP compartilham a cota de API. As assinaturas do scraper Online e da Extensão têm cotas separadas. Limites de taxa, credenciais, capacidade do serviço e disponibilidade da fonte ainda se aplicam.

Comparar planos de API →

Timeouts e novas tentativas

Permita até 180 segundos no seu cliente HTTP. Um timeout pode deixar trabalho em processamento com uma unidade de requisição reservada. Reutilize o corpo idêntico e a Idempotency-Key para repetir essa requisição. Verifique os detalhes do erro e a possibilidade de nova tentativa antes de iniciar uma nova tentativa.

Entenda as novas tentativas →

Continue seu fluxo de trabalho

Mais formas de usar os mesmos dados de empresas.

01

Dados de avaliações e galeria

Recupere avaliações públicas ou metadados de fotos e vídeos de um lugar usando seu feature ID.

Explorar dados de galeria
02

Conecte um cliente MCP

Permita que um cliente de IA compatível descubra as ferramentas de pesquisa, avaliações e fotos com suas credenciais de API.

Configurar MCP
03

Instale o Agent Skill

Dê ao seu agente instruções de fluxo de trabalho, referências de operações e um fallback REST para pesquisa no Google Maps.

Explorar a skill

Perguntas frequentes

O que a API de scraping do Google Maps retorna?

Ela retorna um envelope JSON com data.businesses, data.total, data.params normalizados, request_id e schema_version. As empresas incluem campos de ficha disponíveis, como nomes, endereços, categorias, informações de contato, avaliações e identificadores do Maps.

Posso usar a API a partir de Python ou JavaScript?

Sim. O endpoint aceita requisições HTTP POST padrão com JSON e autenticação Bearer. Os exemplos acima usam a biblioteca padrão do Python e fetch de JavaScript no lado do servidor. Qualquer cliente HTTP capaz de enviar esses cabeçalhos e corpo pode integrar.

Quantas empresas uma requisição pode retornar?

Uma página de pesquisa retorna entre zero e 20 empresas. O parâmetro page aceita de 1 a 10. Cada página live bem-sucedida, incluindo uma página vazia, usa uma unidade de requisição de API; uma pesquisa não garante que toda página contenha 20 empresas.

Posso recuperar avaliações e fotos individuais?

Sim. Copie place.dataId de uma empresa e passe-o como fid para a API separada Reviews ou Photos. Esses endpoints retornam uma página delimitada por requisição. A visão geral da API aponta para os campos, exemplos e regras de paginação de cada endpoint.

Endereços de e-mail estão incluídos para toda empresa?

Não. Defina extra como true para solicitar o enriquecimento de contato disponível. Sites, e-mails e perfis sociais podem estar ausentes. Inspecione enrichmentState e fieldStates e mantenha os dados indisponíveis explícitos no seu aplicativo.

Como devo testar uma integração?

Se você tem uma credencial de teste, suas respostas são simuladas e não consomem a cota live da API. Rotule esses resultados como simulados. Chaves live exigem um direito de API ativo e capacidade de serviço disponível, e chamadas live bem-sucedidas usam unidades de requisição.

Dê o próximo passo

Construa sua primeira pesquisa no Google Maps.

Crie uma chave de API, escolha uma consulta e localização e leia dados estruturados de empresas na mesma resposta.