# Google Maps BR Scraper — Anti-Block: Listings & Data (`viralanalyzer/google-maps-br-scraper`) Actor

Scrape Google Maps businesses in Brazil. Extract name, address, phone, rating, reviews, category, CEP. Search by keyword + city with lower-cost default proxy and optional residential fallback.

- **URL**: https://apify.com/viralanalyzer/google-maps-br-scraper.md
- **Developed by:** [viralanalyzer](https://apify.com/viralanalyzer) (community)
- **Categories:** Lead generation, Business
- **Stats:** 48 total users, 0 monthly users, 100.0% runs succeeded, 1 bookmarks
- **User rating**: 5.00 out of 5 stars

## Pricing

from $5.00 / 1,000 business scrapeds

This Actor is paid per event and usage. You are charged both the fixed price for specific events and for Apify platform usage.

Learn more: https://docs.apify.com/actors/running/actors-in-store.md#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 BR Scraper — Business Data + Reviews (Brazil)

> 🔗 [View on Apify Store](https://apify.com/viralanalyzer/google-maps-br-scraper) | 🇺🇸 English | [🇧🇷 Português](#português)

Scrape **Google Maps businesses in Brazil** with full details, reviews, ratings, and CEP enrichment. Search by keyword + city, extract business information, and collect customer reviews with sentiment analysis.

### ✨ Features

- 🔍 **Search by keyword + city** — "restaurantes São Paulo", "dentista Curitiba"
- 📋 **Full business data** — Name, address, phone, rating, category, price level
- ⭐ **Review extraction** — Best-effort extraction of author, rating, text, date (see [Limitations](#limitations))
- 💬 **Sentiment analysis** — Score (-1.0 to 1.0) + label per review
- 📮 **CEP enrichment** — Validates CEP via ViaCEP API
- 🛡️ **Validated output** — Every output validated before delivery
- 🌐 **Portuguese optimized** — Interface language pt-BR by default
- 💰 **Pay per business** — $0.005 per business scraped ($5.00 / 1,000)

### 📥 Input

| Parameter | Type | Required | Default | Description |
|---|---|---|---|---|
| `queries` | string\[] | ✅ | — | Search queries ("keyword + city") |
| `maxPlaces` | integer | ❌ | 10 | Max businesses per query |
| `maxReviews` | integer | ❌ | 5 | Max reviews per business (0 = none) |
| `language` | string | ❌ | "pt-BR" | Interface language |
| `enrichCep` | boolean | ❌ | true | Validate CEP via ViaCEP |
| `proxyConfig` | object | ❌ | Apify Proxy | Proxy settings. Lower-cost proxy is the default; use `RESIDENTIAL` only when needed |

#### Input Example

```json
{
  "queries": [
    "restaurantes São Paulo",
    "dentista Curitiba",
    "hotel Rio de Janeiro"
  ],
  "maxPlaces": 10,
  "maxReviews": 5,
  "language": "pt-BR",
  "enrichCep": true
}
```

### 📤 Output

Every business includes these fields:

| Field | Type | Description |
|---|---|---|
| `business_name` | string | Business name |
| `place_id` | string | Google Maps Place ID |
| `address` | string | Full address |
| `cep` | string | Brazilian postal code (CEP) |
| `phone` | string | Phone number |
| `rating` | number | Google rating (1.0-5.0) |
| `total_reviews` | number | Total review count |
| `category` | string | Business category |
| `price_level` | string | Price level ($, $$, $$$) |
| `url` | string | Google Maps URL |
| `website` | string | Business website |
| `reviews` | object\[] | Extracted reviews (see below) |

#### Review Fields

| Field | Type | Description |
|---|---|---|
| `author` | string | Reviewer name |
| `rating` | number | Review rating (1-5) |
| `text` | string | Review text |
| `date` | string | Review date |
| `sentiment_score` | number | Sentiment score (-1.0 to 1.0) |
| `sentiment_label` | string | muito\_positivo / positivo / neutro / negativo / muito\_negativo |
| `language` | string | Detected language (pt-BR, en) |
| `topics` | string\[] | Detected topics (comida, atendimento, preço, etc.) |

#### Output Example

```json
{
  "business_name": "A Casa do Porco Bar",
  "place_id": "0x94ce59d5ffb08061:0xc15464b7355933729",
  "address": "R. Araújo, 124 - República, São Paulo - SP, 01220-020",
  "cep": "01220020",
  "phone": "(11) 3258-2578",
  "rating": 4.7,
  "total_reviews": 18542,
  "category": "Restaurante brasileiro",
  "price_level": "$$$",
  "latitude": -23.5474,
  "longitude": -46.6395,
  "google_place_id": "ChIJYYCw_9VZzpQRKTNZNbdkVME",
  "neighborhood": "República",
  "timezone": "America/Sao_Paulo",
  "url": "https://www.google.com/maps/place/...",
  "reviews": [
    {
      "author": "João Silva",
      "rating": 5,
      "text": "Melhor restaurante de porco de São Paulo!",
      "date": "1 mês atrás",
      "sentiment_score": 1.0,
      "sentiment_label": "muito_positivo",
      "language": "pt-BR",
      "topics": ["comida"]
    }
  ]
}
```

> **Coordenadas / Coordinates** — `latitude`, `longitude`, `google_place_id`, `neighborhood` e
> `timezone` vêm de um enriquecimento opcional. Quando a fonte de enriquecimento está indisponível,
> esses campos retornam `null` e o restante da extração segue normalmente.
>
> ⚠️ **Atenção ao `place_id`**: ele é o *feature id* do Google (formato `0x...:0x...`), não o Place ID
> da Places API. O identificador canônico (`ChIJ...`) está em **`google_place_id`**. O campo `place_id`
> foi mantido inalterado para não quebrar integrações existentes.

### 📋 Use Cases

- **Market Research** — Map competitors in a city by category
- **Reputation Monitoring** — Track reviews and ratings over time
- **Lead Generation** — Extract business contact info (phone, address)
- **Location Analysis** — Compare ratings across neighborhoods
- **Customer Insights** — Analyze review topics and sentiment

### ⚠️ Limitations

- **Review text extraction is best-effort.** Google Maps actively blocks automated review extraction with aggressive anti-bot measures. Business data (name, address, phone, rating, total review count, category) is extracted reliably. Individual review text may not always be available.
- **Total review count** is always extracted from the business page (e.g., "18,542 reviews") even when individual review text cannot be retrieved.
- **Geographic entities** (cities, states) that appear in search results are automatically filtered out.

### ✅ Capabilities & Limits

Stated up front, so you do not pay a run to find out.

**Built here:** on a free-plan Apify account the actor trims your input before scraping: queries truncated to 1, `maxPlaces` to 2, `maxReviews` to 1, whatever you sent. The gate reads `APIFY_USER_IS_PAYING`, so a free-plan test run can never reproduce paid-plan volume and only a log warning reveals the truncation.

| Input / feature | Supported | Notes |
|---|---|---|
| Search query | ✅ | `queries` — required, in the form `keyword + city` (e.g. `restaurantes São Paulo`) |
| Business volume | ⚠️ | `maxPlaces` per query |
| Reviews | ✅ | `maxReviews` per business; `0` skips reviews and runs much faster |
| CEP validation | ✅ | `enrichCep` cross-checks the address against the ViaCEP API |
| Interface language | ✅ | `language` |
| **E-mail addresses** | ❌ | Google Maps does not publish them — for e-mail leads see `google-maps-business-leads-pro` |
| Owner or decision-maker name | ❌ | not part of a Maps listing |
| Real-time popularity | ❌ | "popular times" is not extracted |
| Proxy | ⚠️ | default uses lower-cost Apify proxy; residential only if blocked |

### ❓ FAQ

**Q: Does this need a Google API key?**
A: No! This actor works without any Google API credentials.

**Q: What proxy does it need?**
A: The default is the lower-cost Apify proxy. Use `RESIDENTIAL` only when Google starts returning stripped pages or zero results.

**Q: Can I search in any Brazilian city?**
A: Yes! Just use the format "keyword + city name" in your queries.

**Q: Why are reviews sometimes empty?**
A: Google Maps uses aggressive anti-bot measures that strip review content from automated browsers. Business data and total review counts are always extracted reliably.

**Q: What sentiment labels are available?**
A: Five levels from muito\_positivo to muito\_negativo, based on review context.

**Q: Does it extract CEP for every business?**
A: Yes, when `enrichCep` is enabled. The CEP is validated via the ViaCEP public API.

### 💰 Pricing

This actor uses **Pay Per Event (PPE)** pricing. The rate depends on your Apify plan tier:

| Plan tier | Per business scraped | Per 1,000 |
|-----------|-----------|-----------|
| All plans | $0.005     | $5.00 |

**You are never charged for a run that returned nothing.** When the source blocks and
nothing is extracted, the actor returns a labeled diagnostic and charges no PPE event.

### 🔗 Related Actors

- [CNPJ Enricher](https://apify.com/viralanalyzer/cnpj-enricher) — Enrich with company data
- [YouTube Fast Scraper](https://apify.com/viralanalyzer/youtube-fast-scraper) — YouTube video metrics
- [TikTok Viral Scanner](https://apify.com/viralanalyzer/tiktok-viral-scanner) — TikTok profile data
- [Instagram Reels Scraper](https://apify.com/viralanalyzer/instagram-reels-scraper) — Instagram metrics

### 📝 Changelog

#### v1.0 (Current)

- ✅ Search by keyword + city
- ✅ Full business data extraction (name, address, phone, rating, total reviews, category)
- ✅ Best-effort review extraction with sentiment analysis
- ✅ CEP enrichment via ViaCEP
- ✅ Geographic entity filtering (skips cities/states)
- ✅ Stealth browsing with lower-cost default proxy and optional residential mode
- ✅ Bilingual support (PT-BR + EN)

***

<a name="português"></a>

## 🗺️ Google Maps BR Scraper — Dados de Empresas + Avaliações

> [🇺🇸 English](#️-google-maps-br-scraper--business-data--reviews-brazil) | 🇧🇷 Português

Extraia **dados de empresas do Google Maps no Brasil** com detalhes completos, avaliações, notas e enriquecimento de CEP. Busque por palavra-chave + cidade, extraia informações do negócio e colete avaliações de clientes com análise de sentimento.

### ✨ Funcionalidades

- 🔍 **Busca por palavra-chave + cidade** — "restaurantes São Paulo", "dentista Curitiba"
- 📋 **Dados completos** — Nome, endereço, telefone, nota, categoria, faixa de preço
- ⭐ **Extração de avaliações** — Extração best-effort de autor, nota, texto, data (veja [Limitações](#limitações))
- 💬 **Análise de sentimento** — Score (-1.0 a 1.0) + label por avaliação
- 📮 **Enriquecimento de CEP** — Validação via API ViaCEP
- 🛡️ **Output validado** — Todo output validado antes da entrega
- 🌐 **Otimizado para português** — Interface pt-BR por padrão
- 💰 **Pague por empresa** — $0.005 por empresa extraída ($5.00 / 1.000)

### 📥 Entrada

| Parâmetro | Tipo | Obrigatório | Padrão | Descrição |
|---|---|---|---|---|
| `queries` | string\[] | ✅ | — | Buscas ("palavra-chave + cidade") |
| `maxPlaces` | inteiro | ❌ | 10 | Máx empresas por busca |
| `maxReviews` | inteiro | ❌ | 5 | Máx avaliações por empresa (0 = nenhuma) |
| `language` | string | ❌ | "pt-BR" | Idioma da interface |
| `enrichCep` | boolean | ❌ | true | Validar CEP via ViaCEP |
| `proxyConfig` | objeto | ❌ | Apify Proxy | Config de proxy. O modo padrao e mais barato; use `RESIDENTIAL` so quando precisar |

#### Exemplo de Entrada

```json
{
  "queries": [
    "restaurantes São Paulo",
    "dentista Curitiba",
    "hotel Rio de Janeiro"
  ],
  "maxPlaces": 10,
  "maxReviews": 5,
  "language": "pt-BR",
  "enrichCep": true
}
```

### 📤 Saída

Cada empresa inclui estes campos:

| Campo | Tipo | Descrição |
|---|---|---|
| `business_name` | string | Nome da empresa |
| `place_id` | string | Google Maps Place ID |
| `address` | string | Endereço completo |
| `cep` | string | CEP (código postal) |
| `phone` | string | Telefone |
| `rating` | número | Nota Google (1.0-5.0) |
| `total_reviews` | número | Total de avaliações |
| `category` | string | Categoria da empresa |
| `price_level` | string | Faixa de preço ($, $$, $$$) |
| `url` | string | URL do Google Maps |
| `website` | string | Site da empresa |
| `reviews` | objeto\[] | Avaliações extraídas (ver abaixo) |

#### Campos da Avaliação

| Campo | Tipo | Descrição |
|---|---|---|
| `author` | string | Nome do avaliador |
| `rating` | número | Nota (1-5) |
| `text` | string | Texto da avaliação |
| `date` | string | Data |
| `sentiment_score` | número | Score de sentimento (-1.0 a 1.0) |
| `sentiment_label` | string | muito\_positivo / positivo / neutro / negativo / muito\_negativo |
| `language` | string | Idioma detectado (pt-BR, en) |
| `topics` | string\[] | Tópicos detectados (comida, atendimento, preço, etc.) |

### 📋 Casos de Uso

- **Pesquisa de mercado** — Mapeie concorrentes por cidade e categoria
- **Monitoramento de reputação** — Acompanhe avaliações e notas ao longo do tempo
- **Geração de leads** — Extraia contatos (telefone, endereço)
- **Análise de localização** — Compare notas entre bairros
- **Insights de clientes** — Analise tópicos e sentimento das avaliações

### ⚠️ Limitações

- **Extração de texto de avaliações é best-effort.** O Google Maps bloqueia ativamente a extração automatizada de avaliações com medidas anti-bot agressivas. Dados de negócios (nome, endereço, telefone, nota, total de avaliações, categoria) são extraídos de forma confiável.
- **Contagem total de avaliações** é sempre extraída da página da empresa, mesmo quando o texto individual não está disponível.
- **Entidades geográficas** (cidades, estados) que aparecem nos resultados são filtradas automaticamente.

### ❓ Perguntas Frequentes

**P: Precisa de chave da API do Google?**
R: Não! Este actor funciona sem nenhuma credencial de API do Google.

**P: Que tipo de proxy precisa?**
R: O padrao agora usa o proxy mais barato da Apify. Ative `RESIDENTIAL` apenas quando o Google comecar a devolver pagina capada ou zero resultados.

**P: Posso buscar em qualquer cidade brasileira?**
R: Sim! Use o formato "palavra-chave + nome da cidade" nas queries.

**P: Por que as avaliações às vezes estão vazias?**
R: O Google Maps usa medidas anti-bot agressivas que removem conteúdo de avaliações de navegadores automatizados. Dados do negócio e contagens totais são sempre extraídos.

**P: Quais labels de sentimento estão disponíveis?**
R: Cinco níveis de muito\_positivo a muito\_negativo, baseados no contexto da avaliação.

**P: O CEP é extraído para toda empresa?**
R: Sim, quando `enrichCep` está habilitado. O CEP é validado via API pública ViaCEP.

### 💰 Preços

This actor uses **Pay Per Event (PPE)** pricing. The rate depends on your Apify plan tier:

| Plan tier | Per business scraped | Per 1,000 |
|-----------|-----------|-----------|
| All plans | $0.005     | $5.00 |

**You are never charged for a run that returned nothing.** When the source blocks and
nothing is extracted, the actor returns a labeled diagnostic and charges no PPE event.

### 🔗 Actors Relacionados

- [CNPJ Enricher](https://apify.com/viralanalyzer/cnpj-enricher) — Enriquecimento com dados empresariais
- [YouTube Fast Scraper](https://apify.com/viralanalyzer/youtube-fast-scraper) — Métricas do YouTube
- [TikTok Viral Scanner](https://apify.com/viralanalyzer/tiktok-viral-scanner) — Dados do TikTok
- [Instagram Reels Scraper](https://apify.com/viralanalyzer/instagram-reels-scraper) — Métricas do Instagram

# Actor input Schema

## `queries` (type: `array`):

List of search queries. Format: 'keyword + city' (e.g., 'restaurantes São Paulo', 'dentista Curitiba')

## `maxPlaces` (type: `integer`):

Maximum number of businesses to extract per search query

## `maxReviews` (type: `integer`):

Maximum number of reviews to extract per business (0 = no reviews)

## `language` (type: `string`):

Google Maps interface language

## `enrichCep` (type: `boolean`):

Try to extract and validate CEP from address using ViaCEP API

## `proxyConfig` (type: `object`):

Proxy settings for the scraper. Default mode uses lower-cost Apify proxy; enable RESIDENTIAL only if Google starts returning stripped pages or zero results.

## Actor input object example

```json
{
  "queries": [
    "restaurantes São Paulo",
    "dentista Curitiba",
    "hotel Rio de Janeiro"
  ],
  "maxPlaces": 3,
  "maxReviews": 5,
  "language": "pt-BR",
  "enrichCep": true,
  "proxyConfig": {
    "useApifyProxy": true
  }
}
```

# Actor output Schema

## `results` (type: `string`):

Dataset containing all scraped results. Each item follows the dataset schema.

# 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 = {
    "queries": [
        "pizzaria Curitiba"
    ],
    "maxPlaces": 3,
    "maxReviews": 0,
    "language": "pt-BR",
    "enrichCep": true,
    "proxyConfig": {
        "useApifyProxy": true
    }
};

// Run the Actor and wait for it to finish
const run = await client.actor("viralanalyzer/google-maps-br-scraper").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 = {
    "queries": ["pizzaria Curitiba"],
    "maxPlaces": 3,
    "maxReviews": 0,
    "language": "pt-BR",
    "enrichCep": True,
    "proxyConfig": { "useApifyProxy": True },
}

# Run the Actor and wait for it to finish
run = client.actor("viralanalyzer/google-maps-br-scraper").call(run_input=run_input)

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

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

```

## CLI example

```bash
echo '{
  "queries": [
    "pizzaria Curitiba"
  ],
  "maxPlaces": 3,
  "maxReviews": 0,
  "language": "pt-BR",
  "enrichCep": true,
  "proxyConfig": {
    "useApifyProxy": true
  }
}' |
apify call viralanalyzer/google-maps-br-scraper --silent --output-dataset

```

## MCP server setup

```json
{
    "mcpServers": {
        "apify": {
            "type": "http",
            "url": "https://mcp.apify.com/?tools=fetch-actor-details,viralanalyzer/google-maps-br-scraper"
        }
    }
}

```

The hosted server signs you in with OAuth on first connect, so no API token belongs in this config. Clients without OAuth support can send an `Authorization: Bearer <APIFY_API_TOKEN>` header instead, using a token from API & Integrations in Apify Console (https://console.apify.com/settings/integrations).

## OpenAPI specification

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