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.
POST /api/v1/search
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.
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.
{
"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
Leia data.businesses da resposta. Cada empresa agrupa seus campos de ficha sob place; a disponibilidade dos campos depende da fonte.
Use o nome da empresa, categorias, endereço formatado, coordenadas e URL do Maps para organizar um dataset de empresas locais.
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.
Guarde place.dataId para consultas de avaliações e fotos. Inspecione place.observedAt e contactsCheckedAt para entender quando os dados foram observados.
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
Envie um corpo JSON com sua chave de API do lado do servidor no cabeçalho de autorização. Apenas q é obrigatório.
| Parâmetro | Requisito | Finalidade |
|---|---|---|
| q | Obrigatório | Uma palavra-chave de empresa e localização, como cafeterias em Seattle. Use de 2 a 200 caracteres. |
| page | Padrão: 1 | Uma página de pesquisa numerada de 1 a 10. Cada requisição retorna no máximo 20 empresas. |
| ll | Opcional | Um viewport do Maps no formato @47.6062,-122.3321,12z para orientar a localização da pesquisa. |
| hl | Padrão: en | O código de idioma usado para a pesquisa. |
| gl | Opcional | Um código de país de duas letras que qualifica a consulta. Não é um filtro geográfico estrito. |
| extra | Padrão: false | Defina 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
A Search API é síncrona: leia o resultado diretamente da resposta HTTP.
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 APIEscolha 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.
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 APIPlaneje para requisições reais
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 →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
Recupere avaliações públicas ou metadados de fotos e vídeos de um lugar usando seu feature ID.
Explorar dados de galeriaPermita que um cliente de IA compatível descubra as ferramentas de pesquisa, avaliações e fotos com suas credenciais de API.
Configurar MCPDê 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 skillEla 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.
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.
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.
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.
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.
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
Crie uma chave de API, escolha uma consulta e localização e leia dados estruturados de empresas na mesma resposta.