# Google Maps Brasil — Leads Locais com E-mail, Telefone e CNPJ (`paulovitor18/gmaps-brasil-leads`) Actor

Extraia leads locais do Google Maps no Brasil já com telefone, site, e-mail e o CNPJ da Receita Federal — pronto pra prospecção. Pague por resultado.

- **URL**: https://apify.com/paulovitor18/gmaps-brasil-leads.md
- **Developed by:** [MoreLock](https://apify.com/paulovitor18) (community)
- **Categories:** Lead generation
- **Stats:** 7 total users, 3 monthly users, 100.0% runs succeeded, 0 bookmarks
- **User rating**: No ratings yet

## Pricing

Pay per event

This Actor is paid per event. You are not charged for the Apify platform usage, but only a fixed price for specific events.

Learn more: https://docs.apify.com/platform/actors/running/actors-in-store#pay-per-event

## What's an Apify Actor?

Actors are web data automations that power AI and operations. They run on the Apify platform to scrape websites, process data, connect APIs, and automate workflows.
In Batch mode, an Actor accepts a well-defined JSON input, performs an action which can take anything from a few seconds to a few hours,
and optionally produces a well-defined JSON output, datasets with results, or files in key-value store.
In Standby mode, an Actor provides a web server which can be used as a website, API, or an MCP server.
Actors are written with capital "A".

## How to integrate an Actor?

If asked about integration, you help developers integrate Actors into their projects.
You adapt to their stack and deliver integrations that are safe, well-documented, and production-ready.
The best way to integrate Actors is as follows.

- **AI agents and MCP clients** — the [Apify MCP server](https://docs.apify.com/integrations/mcp.md) at `https://mcp.apify.com` (remote, streamable HTTP, OAuth on first use).
- **Agentic workflows and local Actor development** — [Agent Skills](https://apify.com/.well-known/agent-skills/index.json) with the [Apify CLI](https://docs.apify.com/cli/docs.md): `npm install -g apify-cli`, then `apify login`.
- **JavaScript/TypeScript projects** — the official [JS/TS client](https://docs.apify.com/api/client/js/docs.md): `npm install apify-client`.
- **Python projects** — the official [Python client](https://docs.apify.com/api/client/python/docs.md): `pip install apify-client`.
- **Any other language** — the [REST API](https://docs.apify.com/api/v2.md).

For usage examples, see the [API](#api) section below.

For more details, see Apify documentation as [Markdown index](https://docs.apify.com/llms.txt) and [Markdown full-text](https://docs.apify.com/llms-full.txt).

# README

## Google Maps Brasil — Leads Locais com E-mail, Telefone e CNPJ

Extraia listas de estabelecimentos do Google Maps já com o contato pronto para prospecção — telefone, site, e-mail, redes sociais — e, quando o site publica o CNPJ, os dados oficiais da Receita Federal no mesmo registro.

### Visão geral

Você digita o que procura e onde ("restaurantes" em "Florianópolis, SC") e recebe uma tabela de leads locais. Cada estabelecimento sai com nome, categoria, nota, número de avaliações e localização; ligando a hidratação de detalhes, também com telefone, site oficial, endereço completo, CEP e GPS preciso. O diferencial vem depois: quando o estabelecimento tem site e ele publica o CNPJ em texto, o Actor valida esse CNPJ pelo dígito verificador e consulta a Receita Federal — razão social, situação cadastral, porte, capital social, CNAE e quadro de sócios entram no mesmo lead.

É um raspador brasileiro, não um raspador genérico com português colado: o parsing entende os cards do Maps em pt-BR (nota "4,7", "(4.973)" avaliações, faixa "R$ 80–200") e o enriquecimento fala com a Receita, não com um diretório internacional.

### Features

- Busca geolocalizada por termo + cidade, com rolagem automática do feed até o teto que você definir.
- Contato pronto por estabelecimento: telefone (exibição e só-dígitos), site, e-mail, Instagram, WhatsApp e Facebook.
- Endereço completo com CEP e coordenadas GPS precisas (via hidratação da ficha de detalhe).
- Enriquecimento por CNPJ: busca o número no site do estabelecimento (com validação do dígito verificador) e consulta a Receita Federal — BrasilAPI, com fontes de reserva gratuitas caso a principal esteja fora do ar.
- Guarda de match: o CNPJ só é afirmado como "confiança alta" quando a razão social ou o nome fantasia casa com o nome do estabelecimento — senão vem marcado `baixa` (pode ser uma entidade do grupo, não a filial exata).
- Cobrança honesta: estabelecimento sem site, ou com site sem CNPJ raspável, NÃO gera cobrança de enriquecimento.

### Input example

```json
{
  "termo": "restaurantes",
  "local": "Florianópolis, SC",
  "max_resultados": 40,
  "hidratar_detalhes": true,
  "max_hidratacoes": 40,
  "enriquecer_cnpj": true,
  "proxy": { "useApifyProxy": true }
}
```

### Output example

```json
{
  "place_id": "ChIJb9Ls7l0-J5UR75CXQFqDFT4",
  "nome": "O Timoneiro",
  "categoria": "Restaurante de frutos do mar",
  "endereco": "R. Laurindo José de Souza, 205 - Barra da Lagoa, Florianópolis - SC, 88061-400",
  "cep": "88061-400",
  "uf": "SC",
  "telefone": "(48) 3204-4084",
  "telefone_digits": "4832044084",
  "site": "http://www.restauranteotimoneiro.com/",
  "email": null,
  "instagram": null,
  "rating": 4.7,
  "reviews_count": 4973,
  "lat": -27.588313,
  "lng": -48.434095,
  "place_url": "https://www.google.com/maps/place/O+Timoneiro/...",
  "sponsored": false,
  "hidratado": true,
  "cnpj": null,
  "razao_social": null,
  "situacao_cadastral": null,
  "cnpj_enriquecido": false,
  "cnpj_confianca": null,
  "cnpj_obs": "no_cnpj_on_site",
  "coletado_em": "2026-07-16T22:00:00.000Z"
}
```

Quando o site publica o CNPJ, os campos `cnpj`, `razao_social`, `situacao_cadastral`, `porte`, `capital_social`, `cnae_principal` e `socios` vêm preenchidos e `cnpj_enriquecido` fica `true`. Exemplo de um lead **enriquecido** (dados oficiais da Receita no mesmo registro):

```json
{
  "cnpj": "60.840.055/0001-31",
  "razao_social": "FLEURY S.A.",
  "situacao_cadastral": "ATIVA",
  "cnae_principal": "8640-2/02 - Laboratórios clínicos",
  "cnpj_enriquecido": true,
  "cnpj_confianca": "alta"
}
```

(além de `porte`, `capital_social` e o quadro de `socios`).

### Parâmetros

| Campo | Tipo | Padrão | Descrição |
|---|---|---|---|
| `termo` | string | `"restaurantes"` | O que procurar, como você digitaria no Maps. |
| `local` | string | `"Florianópolis, SC"` | Cidade e UF do recorte. |
| `max_resultados` | integer | `40` | Teto de estabelecimentos entregues (controle de custo). Máx. 150; para varreduras grandes, desligue a hidratação. |
| `hidratar_detalhes` | boolean | `true` | Abre a ficha de cada estabelecimento para telefone, site, CEP e GPS. É o passo mais lento; desligue para varredura rápida. |
| `max_hidratacoes` | integer | `40` | Teto de fichas de detalhe abertas (o gargalo de tempo). Máx. 100 por execução; acima disso, rode em lotes. |
| `enriquecer_cnpj` | boolean | `true` | Visita o site (quando existe) para e-mail, redes e CNPJ, e consulta a Receita. |
| `proxy` | object | Apify Proxy | Datacenter rotativo por padrão; troque para Residencial + Brasil se ver bloqueio em volume. |

### Tips

- Refine `termo` + `local` para varrer além do teto de ~120 do Maps: "pizzarias" + "Balneário Camboriú, SC" rende mais que "restaurantes" + "Santa Catarina".
- A hidratação de detalhes é o que transforma uma lista num lead acionável — mas é a etapa mais lenta. Para um primeiro mapeamento de mercado, rode com `hidratar_detalhes: false` e só hidrate o recorte que interessa.
- O enriquecimento por CNPJ é feito na medida do possível: muitos sites carregam o conteúdo por JavaScript (que o raspador não lê) ou só mostram o CNPJ na finalização da compra. Trate `cnpj` preenchido como bônus qualificado, não como cobertura garantida.
- Confira `cnpj_confianca`: `baixa` significa que o CNPJ do site pode ser de uma entidade do grupo (matriz, braço distribuidor), não da unidade exata daquele ponto no mapa.

### Use cases

- **Prospecção B2B local:** monte uma lista de restaurantes, clínicas ou academias de uma cidade com telefone e e-mail para uma campanha de outreach.
- **Qualificação por CNPJ:** cruze o lead com a situação cadastral na Receita antes de abordar — descarte quem está BAIXADO, priorize quem está ATIVO.
- **Pesquisa de mercado:** conte quantos concorrentes de um segmento existem num bairro, com nota média e volume de avaliações.
- **Enriquecimento de CRM:** complete cadastros que só têm o nome do estabelecimento com telefone, site e CNPJ.
- **Due diligence leve:** una o ponto físico (endereço/GPS) à razão social e ao porte da empresa por trás dele.
- **Geração de território de vendas:** agrupe leads por CEP/UF para dividir carteira entre representantes.

### FAQ

**De onde vêm os dados?** Do próprio Google Maps (feed de busca e ficha de detalhe, renderizados) e da Receita Federal via BrasilAPI (com fallback para publica.cnpj.ws e minhareceita.org). Todos são dados públicos.

**Todo lead vem com CNPJ?** Não, e o Actor é honesto quanto a isso. O CNPJ só entra quando o estabelecimento tem site e o site publica o número em texto raspável. Sem site ou sem CNPJ publicado, o campo volta vazio — e você não paga pelo enriquecimento que não aconteceu.

**O que é `cnpj_confianca: "baixa"`?** É o Actor avisando que o CNPJ achado pode não ser o daquela unidade exata. Dois casos: (a) a razão social não bate com o nome do ponto no mapa (matriz ou braço do grupo); (b) **rede** — o mesmo CNPJ apareceu no site de várias filiais deste resultado (site corporativo único), então ele é da rede, não do ponto específico. O dado vai, sempre rotulado. Em caso de rede, o CNPJ é cobrado **1× só**, não por filial.

**Por que preciso de proxy?** O padrão (Apify Proxy datacenter) foi testado e funciona no Google Maps sem captcha. Em volume alto, se aparecer página de consentimento de cookies ou bloqueio, troque para Residencial + país Brasil no seletor de proxy.

**Quantos estabelecimentos por busca?** O Google Maps costuma listar até ~120 por consulta. Para ir além, quebre a busca por bairro, cidade vizinha ou subcategoria.

**Uma busca sem resultado quebra a execução?** Não. Uma busca legítima sem estabelecimentos (ex.: um nicho inexistente numa cidade pequena) retorna uma lista vazia com `empty: true` no resumo — resposta, não erro, e sem cobrança.

### Pricing

Pague por resultado (PPE) — você só paga pelo dado que recebe:

| Evento | Preço | Quando é cobrado |
|---|---|---|
| `place_scraped` | **$8,00 / 1.000** (`$0,008` cada) | Cada estabelecimento entregue no dataset (nome, categoria, telefone, site, rating, GPS, CEP). |
| `cnpj_enriquecido` | **$5,00 / 1.000** (`$0,005` cada) | Só quando um CNPJ real é achado no site e resolvido na Receita. Cobrado **1× por CNPJ único** — rede com N filiais no mesmo CNPJ não multiplica a cobrança. |

**Você NÃO paga por:** estabelecimento sem dado, busca vazia, erro nosso, ou enriquecimento que não aconteceu (site sem CNPJ / sem site = abstenção honesta).

**Exemplo:** uma busca que entrega 40 estabelecimentos, 12 deles com CNPJ resolvido = 40 × `$0,008` + 12 × `$0,005` = **`$0,38`**. A taxa de enriquecimento varia por categoria — varejo, clínicas e serviços formais publicam CNPJ com mais frequência que pequenos comércios locais.

### Related Actors

- **Consulta CNPJ em Lote** — dados da Receita Federal para uma lista de CNPJs.
- **Consulta CEP em Lote** — endereço a partir do CEP.
- **Brazil Due Diligence — CNPJ + Reclame Aqui** — situação cadastral + reputação do consumidor por CNPJ.
- **Reclame Aqui Scraper** — reputação de empresas brasileiras.

### Changelog

- 0.1: primeira versão — busca no Google Maps Brasil, hidratação de detalhes (telefone/site/CEP/GPS), enriquecimento por CNPJ com guarda de match e cobrança multi-evento honesta.

### Contato

Dúvidas, problemas ou pedidos de fonte nova: use a aba Issues do Actor.

# Actor input Schema

## `termo` (type: `string`):

O que procurar no Google Maps, como você digitaria (ex.: "restaurantes", "clínicas odontológicas", "farmácias").

## `local` (type: `string`):

Cidade e UF do recorte (ex.: "Florianópolis, SC"). Quanto mais específico, mais preciso o resultado.

## `max_resultados` (type: `integer`):

Teto de estabelecimentos entregues nesta execução (controle de custo). O Google Maps costuma listar ~120 por busca; refine termo+cidade para varrer além disso. Para varreduras grandes, prefira DESLIGAR a hidratação (abaixo) — sem ela a coleta é rápida mesmo com muitos resultados.

## `hidratar_detalhes` (type: `boolean`):

Abre a ficha de detalhe de cada estabelecimento para extrair telefone, site, endereço completo, CEP e GPS preciso. É o passo que gera o lead de verdade, mas é o mais custoso (uma navegação extra por estabelecimento). Desligue para uma varredura rápida só com nome, categoria, nota e localização aproximada.

## `max_hidratacoes` (type: `integer`):

Limita quantas fichas de detalhe abrir (o passo custoso acima). É o gargalo de tempo: cada ficha é uma navegação. O teto (100) cabe com folga na janela de execução; acima disso, rode em lotes por termo/cidade.

## `enriquecer_cnpj` (type: `boolean`):

Quando o estabelecimento tem site, visita o site uma vez para achar e-mail, redes sociais e o CNPJ; com o CNPJ válido, consulta a Receita Federal (razão social, situação cadastral, porte, capital, CNAE, sócios). É best-effort: muitos sites não publicam CNPJ em texto — nesses casos o campo volta vazio e você NÃO é cobrado pelo enriquecimento.

## `proxy` (type: `object`):

Roteamento de rede. O padrão (Apify Proxy, datacenter rotativo) foi medido devolvendo 200 no Google Maps sem captcha. Se ver bloqueio/consentimento em volume, selecione Residencial + país Brasil.

## `self_test` (type: `boolean`):

Não use em produção. Ignora a busca e roda a bateria de known-answers (parse do feed congelado, busca vazia, enriquecimento do Fleury, abstenção honesta) para provar que o parser e o egresso continuam corretos. Emite um único item de diagnóstico.

## Actor input object example

```json
{
  "termo": "restaurantes",
  "local": "Florianópolis, SC",
  "max_resultados": 40,
  "hidratar_detalhes": true,
  "max_hidratacoes": 40,
  "enriquecer_cnpj": true,
  "proxy": {
    "useApifyProxy": true
  },
  "self_test": false
}
```

# Actor output Schema

## `leads` (type: `string`):

Estabelecimentos entregues nesta execução, no formato descrito em dataset\_schema.json.

## `resumo` (type: `string`):

Contadores da execução: buscados, entregues, hidratados, enriquecidos, abstenções.

# API

You can run this Actor programmatically using our API. Below are code examples in JavaScript, Python, and CLI, as well as the OpenAPI specification and MCP server setup.

## JavaScript example

```javascript
import { ApifyClient } from 'apify-client';

// Initialize the ApifyClient with your Apify API token
// Replace the '<YOUR_API_TOKEN>' with your token
const client = new ApifyClient({
    token: '<YOUR_API_TOKEN>',
});

// Prepare Actor input
const input = {
    "proxy": {
        "useApifyProxy": true
    }
};

// Run the Actor and wait for it to finish
const run = await client.actor("paulovitor18/gmaps-brasil-leads").call(input);

// Fetch and print Actor results from the run's dataset (if any)
console.log('Results from dataset');
console.log(`💾 Check your data here: https://console.apify.com/storage/datasets/${run.defaultDatasetId}`);
const { items } = await client.dataset(run.defaultDatasetId).listItems();
items.forEach((item) => {
    console.dir(item);
});

// 📚 Want to learn more 📖? Go to → https://docs.apify.com/api/client/js/docs

```

## Python example

```python
from apify_client import ApifyClient

# Initialize the ApifyClient with your Apify API token
# Replace '<YOUR_API_TOKEN>' with your token.
client = ApifyClient("<YOUR_API_TOKEN>")

# Prepare the Actor input
run_input = { "proxy": { "useApifyProxy": True } }

# Run the Actor and wait for it to finish
run = client.actor("paulovitor18/gmaps-brasil-leads").call(run_input=run_input)

# Fetch and print Actor results from the run's dataset (if there are any)
print("💾 Check your data here: https://console.apify.com/storage/datasets/" + run["defaultDatasetId"])
for item in client.dataset(run["defaultDatasetId"]).iterate_items():
    print(item)

# 📚 Want to learn more 📖? Go to → https://docs.apify.com/api/client/python/docs/quick-start

```

## CLI example

```bash
echo '{
  "proxy": {
    "useApifyProxy": true
  }
}' |
apify call paulovitor18/gmaps-brasil-leads --silent --output-dataset

```

## MCP server setup

```json
{
    "mcpServers": {
        "apify": {
            "command": "npx",
            "args": [
                "mcp-remote",
                "https://mcp.apify.com/?tools=paulovitor18/gmaps-brasil-leads",
                "--header",
                "Authorization: Bearer <YOUR_API_TOKEN>"
            ]
        }
    }
}

```

## OpenAPI specification

Download the OpenAPI definition: https://api.apify.com/v2/actors/Gp7sSg7Ziza5cZ6A0/builds/yTMEONl6481MKgpxu/openapi.json