# VivaReal Scraper | Brazil Real Estate BRL Pricing (`haketa/vivareal-scraper`) Actor

Scrape vivareal.com.br, Brazil's top property portal. Apartamentos, casas, coberturas & terrenos. FGTS/MCMV eligibility, CRECI license, IPTU+condomínio, quartos/suítes & bairro location.

- **URL**: https://apify.com/haketa/vivareal-scraper.md
- **Developed by:** [Haketa](https://apify.com/haketa) (community)
- **Categories:** Real estate, Developer tools, Automation
- **Stats:** 2 total users, 1 monthly users, 100.0% runs succeeded, NaN bookmarks
- **User rating**: No ratings yet

## Pricing

from $2.50 / 1,000 results

This Actor is paid per event. You are not charged for the Apify platform usage, but only a fixed price for specific events.
Since this Actor supports Apify Store discounts, the price gets lower the higher subscription plan you have.

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

## What's an Apify Actor?

Actors are a software tools running on the Apify platform, for all kinds of web data extraction and automation use cases.
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.

In JavaScript/TypeScript projects, use official [JavaScript/TypeScript client](https://docs.apify.com/api/client/js.md):

```bash
npm install apify-client
```

In Python projects, use official [Python client library](https://docs.apify.com/api/client/python.md):

```bash
pip install apify-client
```

In shell scripts, use [Apify CLI](https://docs.apify.com/cli/docs.md):

````bash
# MacOS / Linux
curl -fsSL https://apify.com/install-cli.sh | bash
# Windows
irm https://apify.com/install-cli.ps1 | iex
```bash

In AI frameworks, you might use the [Apify MCP server](https://docs.apify.com/platform/integrations/mcp.md).

If your project is in a different language, use 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

## VivaReal Scraper — Brazil Real Estate, BRL Pricing, Bairro-Level Apartamentos, Casas, Coberturas & Terrenos

> **The most thorough VivaReal.com.br data extraction tool on Apify.** Pull live property listings from Brazil's largest real estate portal — apartamentos in Pinheiros, coberturas in Leblon, casas in Belo Horizonte, terrenos in Brasília — with **BRL pricing, IPTU + condomínio fees, FGTS/MCMV financing eligibility, CRECI agent licenses, quartos/suítes counts and bairro-level geocoding**, structured and ready for analytics, investor research, prop-tech, and CRM workflows.

[![Apify Actor](https://img.shields.io/badge/Apify-Actor-blue)](https://apify.com/haketa/vivareal-scraper)
[![Live Data](https://img.shields.io/badge/Data-Live%20at%20Runtime-orange)]()
[![Engine](https://img.shields.io/badge/Engine-Playwright%20Chromium-green)]()
[![Pay Per Event](https://img.shields.io/badge/Pricing-Pay%20Per%20Event-yellow)]()
[![Coverage](https://img.shields.io/badge/Markets-All%20BR%20States-purple)]()
[![Region](https://img.shields.io/badge/Country-Brasil%20%F0%9F%87%A7%F0%9F%87%B7-success)]()
[![Currency](https://img.shields.io/badge/Currency-BRL%20R%24-blueviolet)]()
[![No Auth](https://img.shields.io/badge/Authentication-None%20Required-success)]()

---

### What This Actor Does

The **VivaReal Scraper** is a production-ready Apify Actor that extracts the **public property listings catalog** from **[vivareal.com.br](https://www.vivareal.com.br/)** — Brazil's #1 real estate portal and a flagship property of OLX Brasil / Grupo ZAP. It powers the daily property search of millions of Brazilian buyers, renters, and investors across every state in the country.

In a single run the actor returns clean, normalized listing records with the **full Brazilian real estate context** — not just price and bedrooms, but the locally-specific fields that make a listing actually usable for Brazilian use cases: IPTU (annual municipal property tax), condomínio (HOA fees), FGTS/MCMV financing eligibility, CRECI broker license numbers, quartos vs suítes, and bairro-level location inside the standard **UF → cidade → bairro** hierarchy.

The actor covers every transaction type and inventory class VivaReal exposes:

- **Apartamentos** — apartments, the dominant residential format in São Paulo and Rio
- **Casas** — standalone houses (including casa em condomínio and casa de vila)
- **Coberturas** — penthouses (a premium segment in São Paulo and Rio)
- **Kitnets** and **Studios** — compact urban units for renters and students
- **Sobrados** — two-story townhouses
- **Lofts** and **Flats** — boutique/serviced residential formats
- **Terrenos** and **Lotes** — vacant land for development
- **Chácaras, sítios, fazendas** — rural properties
- **Salas comerciais, lojas, galpões** — offices, retail spaces and warehouses

Every record carries **listingId, title, transação (venda/aluguel/lançamento/temporada), price in BRL, condomínio, IPTU, quartos, suítes, banheiros, vagas (parking), area in m², UF, cidade, bairro, publisher type, CRECI license, listing URL, images and scrape timestamp** — the complete payload a Brazilian property analytics pipeline needs.

#### Why scrape VivaReal yourself when this exists?

VivaReal is a modern, JavaScript-rendered single-page application sitting behind **Cloudflare bot protection**. Most teams who attempt a DIY scraper hit the same wall within a week:

- Cloudflare challenges every request that looks even slightly automated — `cf_clearance` cookies expire and force re-challenge
- Listings are rendered into a Next.js `__NEXT_DATA__` blob whose schema **changes between deploys** (field names like `bedrooms`, `quartos`, `unitType`, `propertyType` are inconsistent run-to-run)
- DOM selectors rotate frequently — class names are hashed (`property-card__9xZ2k`) and a release breaks every CSS query that worked yesterday
- BRL price parsing is non-trivial — `R$ 1.500.000,50` uses dots for thousands and a comma for decimal, which trips up every naive `parseFloat`
- Address strings collapse `bairro, cidade, UF` into one comma-separated field with inconsistent ordering
- Pagination silently caps at page 50 — you must detect the cap, not just iterate forever
- IPTU and condomínio appear in different DOM positions depending on listing type (sale vs rent vs lançamento)
- FGTS, MCMV and SFH eligibility are buried inside the free-text description, not in structured fields
- Some search slugs redirect to a **"showcase"** error page when the query has zero results — naive scrapers crash here
- Residential proxies in Brazil are mandatory for any non-trivial volume — datacenter IPs are challenged immediately
- Detecting the `Aguarde…` / `Just a moment…` Cloudflare interstitial requires page-content inspection, not status codes

This actor solves every one of those problems: **Playwright + pt-BR locale + São Paulo timezone + residential proxy session rotation + Next.js JSON-first extraction + DOM fallback + BRL parser + slug-based geocoding + Cloudflare challenge waiter** — packaged as a single Apify run that returns clean JSON in seconds.

---

### Quick Start

#### One-Click Run

1. Open the actor page on [Apify Store](https://apify.com/haketa/vivareal-scraper) and click **Try for free**
2. Pick a **Transaction** (`venda` for sale, `aluguel` for rent, `lancamentos` for new launches) and optionally a city/bairro
3. Set **Max Records** to `50` for a test, or `0` for unlimited
4. Click **Start** — your dataset is ready in seconds; download as JSON, CSV, Excel, or HTML

#### API Run (Python)

```python
from apify_client import ApifyClient

client = ApifyClient("YOUR_APIFY_TOKEN")

run = client.actor("haketa/vivareal-scraper").call(run_input={
    "transacao": "venda",
    "propertyType": "apartamento_residencial",
    "uf": "sp",
    "cidade": "sao-paulo",
    "bairro": "pinheiros",
    "scrapeDetails": False,
    "maxRecords": 200,
    "requestDelay": 2500,
    "proxyConfiguration": {
        "useApifyProxy": True,
        "apifyProxyGroups": ["RESIDENTIAL"],
        "apifyProxyCountry": "BR"
    }
})

for record in client.dataset(run["defaultDatasetId"]).iterate_items():
    print(record["listingId"], record["bairro"], "R$", record["price"], "—", record["quartos"], "quartos")
````

#### API Run (Node.js / TypeScript)

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

const client = new ApifyClient({ token: 'YOUR_APIFY_TOKEN' });

const run = await client.actor('haketa/vivareal-scraper').call({
    transacao: 'aluguel',
    propertyType: 'apartamento_residencial',
    uf: 'rj',
    cidade: 'rio-de-janeiro',
    bairro: 'ipanema',
    maxRecords: 100,
    proxyConfiguration: {
        useApifyProxy: true,
        apifyProxyGroups: ['RESIDENTIAL'],
        apifyProxyCountry: 'BR'
    }
});

const { items } = await client.dataset(run.defaultDatasetId).listItems();
console.log(`Got ${items.length} Ipanema rentals`);
items.slice(0, 5).forEach(it => console.log(it.title, '—', it.price, 'BRL'));
```

#### API Run (cURL)

```bash
curl -X POST "https://api.apify.com/v2/acts/haketa~vivareal-scraper/runs?token=YOUR_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "transacao": "venda",
    "propertyType": "cobertura_residencial",
    "uf": "sp",
    "cidade": "sao-paulo",
    "bairro": "itaim-bibi",
    "maxRecords": 50
  }'
```

#### API Run with direct Start URLs

If you already have hand-crafted VivaReal search URLs (saved searches, custom filters, multi-bairro queries), feed them in directly:

```json
{
  "startUrls": [
    "https://www.vivareal.com.br/venda/sp/sao-paulo/pinheiros/",
    "https://www.vivareal.com.br/venda/sp/sao-paulo/vila-madalena/",
    "https://www.vivareal.com.br/aluguel/rj/rio-de-janeiro/leblon/"
  ],
  "maxRecords": 300
}
```

***

### How It Works

The actor is a **Playwright Chromium** browser fleet tuned for VivaReal's Next.js + Cloudflare stack. Each search task launches a fresh browser context with `pt-BR` locale, `America/Sao_Paulo` timezone, a current Chrome user-agent, and `navigator.webdriver` stealthed to `false`. A **Brazilian residential proxy session** is rotated per task to keep the IP-to-session mapping consistent for Cloudflare.

#### Source URL pattern

VivaReal uses a deterministic URL grammar:

```
https://www.vivareal.com.br/{transacao}/{uf}/{cidade}/{bairro}/{propertyType}/
```

| URL segment | Example | Notes |
|---|---|---|
| `transacao` | `venda`, `aluguel`, `lancamentos`, `temporada` | Required as the first path segment |
| `uf` | `sp`, `rj`, `mg`, `pr`, `rs`, `df`, `sc`, `ba` | Lowercase Brazilian state code |
| `cidade` | `sao-paulo`, `rio-de-janeiro`, `belo-horizonte` | Slugified, accents removed |
| `bairro` | `pinheiros`, `ipanema`, `leblon`, `itaim-bibi` | Slugified neighborhood |
| `propertyType` | `apartamento_residencial`, `casa_residencial`, `cobertura_residencial`, `terreno`, `sala_comercial` | VivaReal's facet slug |
| `?page=N` | `?page=3` | 1-indexed pagination, hard cap around page 50 |

The actor builds these URLs automatically from your structured input, or accepts pre-built URLs via `startUrls`.

#### Extraction strategy

For each search page, the actor runs a **two-tier extraction**:

1. **Next.js JSON-first (`script#__NEXT_DATA__`)** — VivaReal hydrates the search page with a JSON blob containing the full listing array (`props.pageProps.listings` / `results` / `searchResults.listings`). This is the cleanest source and is tried first.
2. **DOM fallback** — if `__NEXT_DATA__` shape changes or is missing, the actor falls back to direct DOM parsing of `[data-type="property"]`, `[class*="property-card"]` and `a[href*="/imovel/"]` cards, augmented with **URL-slug parsing** to recover price (`RS{amount}`), quartos (`{N}-quarto`), area (`{N}m2`) and full **bairro/cidade/UF** from the listing's canonical slug.

#### Bairro-level geocoding

VivaReal listing URLs follow a slug grammar like
`/imovel/apartamento-3-quartos-pinheiros-zona-oeste-sao-paulo-85m2-venda-RS950000-id-2886184081/`.
The actor reverse-engineers this slug into `bairro=Pinheiros, zona=Zona Oeste, cidade=São Paulo, uf=SP` using a built-in map of all 27 BR state capitals plus the top metropolitan-area municipalities (Niterói, Santos, Campinas, Guarulhos, Osasco, São Bernardo do Campo, Santo André, Ribeirão Preto, Sorocaba, Joinville, Londrina, Maringá, Niterói, Petrópolis, Cabo Frio, Búzios, Praia Grande, Guarujá, etc.).

#### Anti-bot handling

- **Cloudflare interstitial detection** — page title polled for `Just a moment`, `Checking`, `Aguarde`, `403`; waits up to 30 seconds for clearance
- **Residential proxy session rotation** — `session-vrN` per browser launch keeps Cloudflare's session-affinity logic happy
- **Stealth init script** — `navigator.webdriver = false`, `window.chrome = { runtime: {} }`
- **Human-like delays** — configurable `requestDelay` (default 2.5s) between page loads, jitter on every navigation
- **Showcase redirect detection** — searches that return zero results redirect to a `/showcase/` URL; the actor logs and exits the task cleanly instead of crashing

#### Engine summary

| Component | Detail |
|---|---|
| Browser | Chromium via Playwright (headless) |
| Locale | `pt-BR` |
| Timezone | `America/Sao_Paulo` |
| Proxy | Apify `RESIDENTIAL`, Brazilian exit IPs strongly recommended |
| Concurrency | One browser per search task (parallelize by running multiple filtered configs) |
| Deduplication | In-memory `Set` keyed on `listingId`, persisted across pages within a run |
| BRL parser | Strips `R$`, dots as thousand separators, comma → dot decimal |

***

### Input Parameters

```json
{
  "startUrls": [],
  "transacao": "venda",
  "propertyType": "apartamento_residencial",
  "uf": "sp",
  "cidade": "sao-paulo",
  "bairro": "pinheiros",
  "scrapeDetails": false,
  "maxRecords": 100,
  "maxPages": 0,
  "requestDelay": 2500,
  "proxyConfiguration": {
    "useApifyProxy": true,
    "apifyProxyGroups": ["RESIDENTIAL"],
    "apifyProxyCountry": "BR"
  }
}
```

#### Parameter reference

| Parameter | Type | Default | Description |
|---|---|---|---|
| `startUrls` | `array<string>` | `[]` | Direct VivaReal search URLs. Bypasses the structured filters below if non-empty. Useful for hand-crafted multi-bairro queries. |
| `transacao` | `string` | `venda` | Transaction type: `venda` (for sale), `aluguel` (for rent), `lancamentos` (new launches / off-plan), `temporada` (vacation rental), or `all` (sale + rent). |
| `propertyType` | `string` | `all` | Property class: `all`, `apartamento_residencial`, `casa_residencial`, `cobertura_residencial`, `kitnet_residencial`, `studio_residencial`, `terreno`, `sala_comercial`. |
| `uf` | `string` | `""` | Brazilian state code, lowercase. Examples: `sp`, `rj`, `mg`, `pr`, `rs`, `df`, `sc`, `ba`, `pe`, `ce`. Empty = all states. |
| `cidade` | `string` | `""` | City slug. Examples: `sao-paulo`, `rio-de-janeiro`, `belo-horizonte`, `brasilia`, `curitiba`, `porto-alegre`, `salvador`, `recife`, `fortaleza`. |
| `bairro` | `string` | `""` | Neighborhood slug. Examples: `pinheiros`, `vila-madalena`, `itaim-bibi`, `jardins`, `moema`, `ipanema`, `leblon`, `copacabana`, `barra-da-tijuca`. |
| `scrapeDetails` | `boolean` | `false` | If `true`, visits each listing detail page for full description, amenities list, FGTS/MCMV eligibility, CRECI license, lat/lng coordinates, and the complete image gallery. Increases runtime significantly. |
| `maxRecords` | `integer` | `0` | Cap on total listings returned. `0` = unlimited. Use a small value like `50` to sample before a full run. |
| `maxPages` | `integer` | `0` | Cap on pages per search task. `0` = unlimited (VivaReal caps around 50 pages anyway). |
| `requestDelay` | `integer` | `2500` | Milliseconds between page loads. Min `1000`, max `10000`. Lower = faster but higher block risk. |
| `proxyConfiguration` | `object` | Apify `RESIDENTIAL` | Apify proxy configuration. **Brazilian residential proxies strongly recommended** — Cloudflare actively challenges datacenter IPs on vivareal.com.br. |

***

### Output Schema

Every record returned by the actor follows the same flat JSON schema, so downstream consumers (Postgres, BigQuery, Snowflake, Sheets, CRMs) can ingest the dataset without per-category branching.

#### Core listing fields

| Field | Type | Description |
|---|---|---|
| `listingId` | `string` | VivaReal internal listing ID (extracted from URL pattern `id-{N}`) — primary key for dedup and historical diffing |
| `title` | `string` | Listing headline as displayed on the card, or built from parsed slug if missing |
| `transacao` | `string` | Transaction: `Venda`, `Aluguel`, `Lançamento`, or `Temporada` |
| `propertyType` | `string` | Normalized type: `Apartamento`, `Casa`, `Cobertura`, `Casa em Condomínio`, `Casa de Vila`, `Sobrado`, `Kitnet`, `Studio`, `Loft`, `Flat`, `Terreno`, `Chácara`, `Sítio`, `Fazenda`, `Sala Comercial`, `Loja`, `Galpão` |
| `price` | `number` | Asking price in BRL — `null` when listed as "Sob Consulta" / on request |
| `currency` | `string` | Always `BRL` |
| `listingUrl` | `string` | Canonical VivaReal listing URL (query strings stripped) |
| `scrapedAt` | `string` | ISO-8601 UTC timestamp of the run |

#### Brazilian financial context

| Field | Type | Description |
|---|---|---|
| `condominio` | `number` | Monthly condomínio (HOA) fee in BRL |
| `iptu` | `number` | Annual IPTU (municipal property tax) in BRL |
| `acceptsFGTS` | `boolean` | `true` if listing description mentions FGTS (severance fund) financing accepted |
| `acceptsMCMV` | `boolean` | `true` if listing mentions "Minha Casa, Minha Vida" / MCMV federal housing program |

#### Physical attributes

| Field | Type | Description |
|---|---|---|
| `area` | `number` | Usable area in square meters (m²) |
| `quartos` | `integer` | Total bedrooms (dormitórios) |
| `suites` | `integer` | Bedrooms with en-suite bathroom |
| `banheiros` | `integer` | Total bathrooms |
| `vagas` | `integer` | Parking spaces (vagas de garagem) |

#### Location (UF → Cidade → Bairro)

| Field | Type | Description |
|---|---|---|
| `uf` | `string` | Two-letter Brazilian state code (e.g., `SP`, `RJ`, `MG`, `DF`) |
| `cidade` | `string` | Municipality name (e.g., `São Paulo`, `Rio De Janeiro`, `Belo Horizonte`) |
| `bairro` | `string` | Neighborhood name (e.g., `Pinheiros`, `Ipanema`, `Itaim Bibi`) |
| `coordinates` | `object` | `{ "lat": number, "lng": number }` — only populated when `scrapeDetails: true` |

#### Publisher / agent

| Field | Type | Description |
|---|---|---|
| `publisherType` | `string` | `Proprietário` (owner), `Imobiliária` (agency), `Corretor` (broker) |
| `publisherCRECI` | `string` | Real estate broker license (CRECI registration number) when published |
| `agencyName` | `string` | Real estate agency / brokerage name |

#### Detail-page fields (only when `scrapeDetails: true`)

| Field | Type | Description |
|---|---|---|
| `description` | `string` | Full listing description text |
| `features` | `array<string>` | In-unit characteristics (e.g., `Varanda gourmet`, `Cozinha planejada`, `Ar condicionado`) |
| `amenities` | `array<string>` | Building/condo amenities (e.g., `Piscina`, `Academia`, `Salão de festas`, `Portaria 24h`, `Playground`) |
| `images` | `array<string>` | Full URL list for every photo in the gallery |

#### Example: Apartamento for sale in Pinheiros, São Paulo

```json
{
  "listingId": "2886184081",
  "title": "Apartamento — 3 quartos, 85m² — Pinheiros, São Paulo",
  "transacao": "Venda",
  "propertyType": "Apartamento",
  "price": 950000,
  "currency": "BRL",
  "condominio": 1200,
  "iptu": 350,
  "quartos": 3,
  "suites": 1,
  "banheiros": 2,
  "vagas": 1,
  "area": 85,
  "uf": "SP",
  "cidade": "São Paulo",
  "bairro": "Pinheiros",
  "acceptsFGTS": true,
  "acceptsMCMV": null,
  "publisherType": "Imobiliária",
  "publisherCRECI": "99999-J",
  "agencyName": "Exemplo Imóveis",
  "description": null,
  "features": null,
  "amenities": null,
  "images": ["https://resizedimgs.vivareal.com/.../foto-1.jpg"],
  "coordinates": null,
  "listingUrl": "https://www.vivareal.com.br/imovel/apartamento-3-quartos-pinheiros-zona-oeste-sao-paulo-85m2-venda-RS950000-id-2886184081/",
  "scrapedAt": "2026-05-16T09:00:00.000Z"
}
```

#### Example: Cobertura for rent in Leblon, Rio de Janeiro

```json
{
  "listingId": "2901234567",
  "title": "Cobertura duplex — 4 quartos, 220m² — Leblon, Rio de Janeiro",
  "transacao": "Aluguel",
  "propertyType": "Cobertura",
  "price": 28000,
  "currency": "BRL",
  "condominio": 4500,
  "iptu": 1800,
  "quartos": 4,
  "suites": 3,
  "banheiros": 5,
  "vagas": 3,
  "area": 220,
  "uf": "RJ",
  "cidade": "Rio De Janeiro",
  "bairro": "Leblon",
  "acceptsFGTS": null,
  "acceptsMCMV": null,
  "publisherType": "Imobiliária",
  "publisherCRECI": "99999-RJ",
  "agencyName": "Exemplo RJ Imóveis",
  "description": null,
  "features": null,
  "amenities": null,
  "images": ["https://resizedimgs.vivareal.com/.../foto-1.jpg"],
  "coordinates": null,
  "listingUrl": "https://www.vivareal.com.br/imovel/cobertura-4-quartos-leblon-zona-sul-rio-de-janeiro-220m2-aluguel-RS28000-id-2901234567/",
  "scrapedAt": "2026-05-16T09:00:00.000Z"
}
```

***

### Property Type Reference

VivaReal categorizes inventory in Portuguese — the actor normalizes these into a canonical set so downstream filters and dashboards stay consistent.

#### Residential

| Normalized type | Portuguese meaning | Typical buyer |
|---|---|---|
| `Apartamento` | Apartment in a multi-unit building | Urban families, professionals — dominant in SP and RJ |
| `Cobertura` | Penthouse (top-floor apartment, often duplex) | Premium / luxury segment |
| `Casa` | Standalone house | Suburban families, lower-density metros |
| `Casa em Condomínio` | House inside a gated condominium | Security-conscious families |
| `Casa de Vila` | Townhouse in a small private alley | Boutique central neighborhoods |
| `Sobrado` | Two-story townhouse | Middle-class suburban |
| `Kitnet` | Studio apartment, small footprint | Students, single renters |
| `Studio` | Modern open-plan studio | Young professionals |
| `Loft` | Industrial-style open-plan unit | Urban creatives |
| `Flat` | Serviced residential apartment | Corporate, short-term residents |

#### Rural / Land

| Normalized type | Portuguese meaning |
|---|---|
| `Terreno` | Land lot for development |
| `Chácara` | Small rural property with house |
| `Sítio` | Medium rural property |
| `Fazenda` | Large rural farm |

#### Commercial

| Normalized type | Portuguese meaning |
|---|---|
| `Sala Comercial` | Commercial office unit |
| `Loja` | Retail storefront |
| `Galpão` | Warehouse / industrial shed |

#### Transaction types

| Value | Portuguese | English |
|---|---|---|
| `Venda` | venda | For sale |
| `Aluguel` | aluguel | For rent (long-term) |
| `Lançamento` | lançamento | New off-plan launch / pre-construction |
| `Temporada` | temporada | Short-term vacation rental |

***

### Use Cases

#### Brazilian Real Estate Investor Research

Buy-to-let investors, real estate funds (FIIs), and property syndicates use the dataset to:

- **Benchmark cap rates** by computing `aluguel / venda` ratios across the same bairro in São Paulo, Rio, Belo Horizonte and Brasília
- **Spot mispriced listings** by joining `price`, `area` (R$/m²), and recent comparables in the same bairro
- **Track new launches (lançamentos)** in Itaim Bibi, Vila Madalena, Pinheiros, Barra da Tijuca, Asa Sul and Águas Claras
- **Quantify condomínio + IPTU drag** on yield — the two fees that DIY ROI calculators usually ignore
- **Identify FGTS/MCMV-eligible inventory** for funds focused on the federally subsidized first-home segment

#### Prop-Tech Startups & iBuying

Brazilian prop-tech operators (avaliação, iBuying, marketplaces, mortgage origination) use the data to:

- **Train AVM (automated valuation) models** with bairro-segmented hedonic regressions
- **Power CMA (Comparative Market Analysis) reports** for new homeowner-acquisition flows
- **Bootstrap listings inventory** before signing exclusive agreements with brokerages
- **Backfill SaaS dashboards** for the Brazilian incumbents (Loft, QuintoAndar, Apto, EmCasa)
- **Validate AI-generated description quality** against real VivaReal listings

#### IPTU & Condomínio Fee Benchmarking

Property managers, accountants, and individual owners use the dataset to:

- **Benchmark condomínio fees** by building age, amenity tier, and bairro
- **Spot anomalies in IPTU assessments** that may be worth appealing at the municipal level
- **Build expense models** for landlord net-yield calculators (`receita_aluguel − iptu/12 − condomínio − vacância`)
- **Inform syndic / administradora pricing** for new building takeovers

#### Expat & Diplomatic Relocation

International firms relocating staff to São Paulo, Rio, Brasília, Curitiba and Belo Horizonte use the dataset to:

- **Build neighborhood comparison briefs** with median rent, IPTU, condomínio per zona
- **Identify FGTS-ineligible / cash-only luxury inventory** for senior expat compensation packages
- **Benchmark school-adjacent rentals** in Jardins, Moema, Leblon, Ipanema, Asa Sul
- **Map walkability and amenity density** per bairro using the building amenities array

#### Mortgage Intelligence (Caixa, Itaú, Bradesco, Santander Brasil)

Mortgage origination teams at major Brazilian banks and fintechs use the data to:

- **Quantify FGTS/MCMV/SFH-eligible inventory share** per metro for product marketing
- **Identify hot bairros** for mortgage acquisition campaigns
- **Benchmark loan-to-value ratios** against current asking prices
- **Build B2B partnership pipelines** with high-volume listing agencies

#### Journalism, Academic & Public-Interest Research

Journalists at Folha, O Globo, Estadão, Valor Econômico and academic researchers use the dataset to:

- **Document gentrification patterns** in Vila Madalena, Pinheiros, Vila Olímpia, Barra da Tijuca, Asa Sul, Praia do Canto
- **Quantify housing affordability** vs. minimum-wage trends
- **Track the post-pandemic interior migration** (São Paulo → Sorocaba, Campinas; Rio → Niterói, Petrópolis, Búzios)
- **Investigate informal-market integration** with the formal listings ecosystem
- **Cover Real Estate Investment Trusts (Fundos Imobiliários — FIIs)** with empirical price data

#### Real Estate Brokerage Lead Generation

Imobiliárias, corretores autônomos, and Brazilian PropTech CRMs use VivaReal data to:

- **Build owner-listed (Proprietário) lead lists** filtered by bairro and price range — direct outreach for representation
- **Identify high-CRECI agencies** dominating specific bairros for partnership / acquisition
- **Map competitive listing density** per bairro to inform commission negotiation
- **Enrich Pipedrive / Salesforce / RD Station** records with current asking prices

#### Construction & Developer Market Intelligence

Brazilian developers (MRV, Cyrela, Tecnisa, Eztec, Even, JHSF, Direcional) use the dataset to:

- **Track lançamento (new launch) prices** by competitor in target submarkets
- **Identify high-demand bairros** for land acquisition
- **Benchmark unit mix decisions** (% 1-quarto vs 2-quartos vs 3-quartos vs 4-quartos) against actual listings
- **Monitor competitor sell-out velocity** by re-scraping launch projects week-over-week

#### Tax & Compliance Advisory

Brazilian tax advisors and contadores use the dataset to:

- **Build "valor de mercado" comparables** for capital-gains (ganho de capital) calculations on property sales
- **Support ITBI (Imposto sobre Transmissão) appeals** against inflated municipal reference prices
- **Document arm's-length pricing** for related-party transfers

***

### Sample Queries & Recipes

#### Recipe 1: All for-sale apartamentos in Pinheiros, São Paulo

```json
{
  "transacao": "venda",
  "propertyType": "apartamento_residencial",
  "uf": "sp",
  "cidade": "sao-paulo",
  "bairro": "pinheiros",
  "maxRecords": 500
}
```

#### Recipe 2: Premium coberturas in Leblon and Ipanema

```json
{
  "startUrls": [
    "https://www.vivareal.com.br/venda/rj/rio-de-janeiro/leblon/cobertura_residencial/",
    "https://www.vivareal.com.br/venda/rj/rio-de-janeiro/ipanema/cobertura_residencial/"
  ],
  "maxRecords": 300
}
```

#### Recipe 3: Long-term aluguel inventory in Itaim Bibi, Vila Olímpia, Jardins

```json
{
  "startUrls": [
    "https://www.vivareal.com.br/aluguel/sp/sao-paulo/itaim-bibi/",
    "https://www.vivareal.com.br/aluguel/sp/sao-paulo/vila-olimpia/",
    "https://www.vivareal.com.br/aluguel/sp/sao-paulo/jardins/"
  ],
  "maxRecords": 600
}
```

#### Recipe 4: All new launches (lançamentos) in Brasília's Asa Sul and Águas Claras

```json
{
  "transacao": "lancamentos",
  "uf": "df",
  "cidade": "brasilia",
  "maxRecords": 300,
  "scrapeDetails": true
}
```

#### Recipe 5: Terrenos for development in greater Curitiba

```json
{
  "transacao": "venda",
  "propertyType": "terreno",
  "uf": "pr",
  "cidade": "curitiba"
}
```

#### Recipe 6: Vacation rentals (temporada) in Búzios and Cabo Frio

```json
{
  "startUrls": [
    "https://www.vivareal.com.br/temporada/rj/buzios/",
    "https://www.vivareal.com.br/temporada/rj/cabo-frio/"
  ],
  "maxRecords": 200
}
```

#### Recipe 7: Test run — sample 30 records before committing to a full city scrape

```json
{
  "transacao": "venda",
  "uf": "mg",
  "cidade": "belo-horizonte",
  "maxRecords": 30
}
```

#### Recipe 8: Full detail scrape of casas in Barra da Tijuca (with descriptions, amenities, coordinates, gallery)

```json
{
  "transacao": "venda",
  "propertyType": "casa_residencial",
  "uf": "rj",
  "cidade": "rio-de-janeiro",
  "bairro": "barra-da-tijuca",
  "scrapeDetails": true,
  "maxRecords": 100
}
```

***

### Integration Examples

#### Google Sheets (via Apify Integration)

1. Schedule the actor in the Apify Console (e.g., daily at 07:00 BRT)
2. Attach the **"Save to Google Sheets"** integration to the schedule
3. Receive a fresh tab per run with every listing in your target bairros, ready for filtering and pivot tables

#### Make.com / Zapier / n8n

Use the **Apify** connector on any of these platforms. Trigger downstream workflows on:

- **New listings** (today's run minus yesterday's, joined on `listingId`)
- **Price drops** (`price_today < price_yesterday` for the same `listingId`)
- **Status removal** (listing in yesterday's dataset but not today's = sold or withdrawn)
- **New CRECI agents** appearing in a given bairro (lead-gen for franchise recruiters)

#### Power BI / Tableau / Looker / Metabase

Connect Apify's REST API as a JSON data source. Build dashboards covering:

- Median R$/m² by bairro across São Paulo, Rio, Belo Horizonte
- IPTU + condomínio drag on net rental yield
- FGTS/MCMV eligible inventory share per metro
- Lançamento launch velocity by developer
- Listings-per-bairro density heatmaps

#### Postgres / Snowflake / BigQuery

Use the [Apify webhook integration](https://docs.apify.com/platform/integrations/webhooks) to POST run results to your warehouse ingestion endpoint. Recommended primary key: `listingId`. Recommended partition: `scrapedAt::date`. Recommended clustering: `uf, cidade, bairro`.

```sql
CREATE TABLE vivareal_listings (
    listing_id    TEXT,
    snapshot_date DATE,
    transacao     TEXT,
    property_type TEXT,
    price_brl     NUMERIC,
    condominio    NUMERIC,
    iptu          NUMERIC,
    quartos       INT,
    suites        INT,
    banheiros     INT,
    vagas         INT,
    area_m2       NUMERIC,
    uf            CHAR(2),
    cidade        TEXT,
    bairro        TEXT,
    creci         TEXT,
    listing_url   TEXT,
    raw           JSONB,
    PRIMARY KEY (listing_id, snapshot_date)
) PARTITION BY RANGE (snapshot_date);
```

#### Salesforce / HubSpot / RD Station CRM enrichment

Trigger a daily Apify run filtered by your target bairros, then upsert into your CRM keyed on `listingId`. Use **price drops** and **status removals** to auto-create Tasks or open Cases for your sales reps.

#### Webhooks for alerting

Wire Apify's run-finished webhook to your team's Slack/Discord/Telegram bot. Push a "new listings today in {bairro}" digest, or alert on luxury-tier coberturas matching a specific buyer's profile.

***

### Major Brazilian Markets at a Glance

| Metro / State | Population | Notable bairros for scraping |
|---|---|---|
| **São Paulo, SP** | 22.6M (greater SP) | Pinheiros, Vila Madalena, Itaim Bibi, Jardins, Moema, Vila Olímpia, Brooklin, Higienópolis, Perdizes, Vila Mariana |
| **Rio de Janeiro, RJ** | 13.6M (greater RJ) | Ipanema, Leblon, Copacabana, Barra da Tijuca, Botafogo, Flamengo, Tijuca, Recreio, Jardim Botânico |
| **Belo Horizonte, MG** | 6.0M | Savassi, Lourdes, Funcionários, Belvedere, Buritis, Sion |
| **Brasília, DF** | 4.7M | Asa Sul, Asa Norte, Águas Claras, Lago Sul, Lago Norte, Sudoeste, Noroeste |
| **Salvador, BA** | 3.7M | Pituba, Barra, Graça, Itaigara, Caminho das Árvores |
| **Curitiba, PR** | 3.6M | Batel, Água Verde, Bigorrilho, Ecoville, Cabral |
| **Porto Alegre, RS** | 4.4M | Moinhos de Vento, Bela Vista, Petrópolis, Auxiliadora |
| **Recife, PE** | 4.1M | Boa Viagem, Casa Forte, Pina, Aflitos |
| **Fortaleza, CE** | 4.1M | Meireles, Aldeota, Cocó, Mucuripe, Varjota |
| **Niterói, RJ** | 0.5M | Icaraí, Ingá, Santa Rosa, São Francisco |
| **Campinas, SP** | 3.4M | Cambuí, Nova Campinas, Jardim Chapadão |
| **Florianópolis, SC** | 1.2M | Jurerê Internacional, Lagoa da Conceição, Centro |
| **Búzios / Cabo Frio, RJ** | Vacation | Geribá, Manguinhos, Ferradura — temporada inventory |

***

### Cost & Performance

| Metric | Value |
|---|---|
| Engine | Playwright Chromium (headless), Brazilian residential proxy |
| Runtime (sample, 50 records, single bairro) | ~30–90 seconds |
| Runtime (full bairro, 500 records) | 5–15 minutes |
| Runtime (full city across all bairros) | 30–90 minutes |
| Memory footprint | 1 GB minimum, 2–4 GB recommended for parallel sessions |
| Pricing model | Pay-per-event — actor start + per dataset item |
| Data freshness | Live at runtime — VivaReal listings update continuously |
| Auth required | None |
| Proxy required | Brazilian RESIDENTIAL strongly recommended (Cloudflare active) |
| Concurrency | Safe — run multiple parallel filtered configs for different bairros |
| Captcha handling | Cloudflare interstitial detected and waited on automatically |

> **Cost note:** because the actor uses pay-per-event pricing, a 50-record sample run costs cents; a full multi-bairro daily scrape across a metro costs a small predictable amount that scales linearly with records returned, not with browser runtime.

***

### Compliance, Privacy & Legal Notes

- **Public data only** — every field this actor returns is publicly visible on [vivareal.com.br](https://www.vivareal.com.br/) without login
- **No personal data of buyers or renters** — VivaReal does not expose buyer-side PII
- **CRECI license numbers are public registrations** — Brazilian law mandates CRECI display on all real estate ads (Lei 6.530/78)
- **Photos remain copyright of the original publisher** — store image URLs, not the binaries, unless you have a license
- **Respect VivaReal's Terms of Service** — do not republish full listings or build a competing portal; analytics, internal CRM, dashboards and aggregated insights are the supported use cases
- **LGPD (Lei Geral de Proteção de Dados)** — the dataset does not contain personal data of property buyers/renters; CRECI numbers and agency names are professional public registrations, generally outside LGPD's "dados pessoais" definition, but consult counsel for your specific downstream use
- **GDPR / CCPA** — listing data is property-side, not consumer-side; standard scraping caveats apply
- **Rate-limit responsibly** — keep `requestDelay >= 2500ms` and use Brazilian RESIDENTIAL proxies; do not run high-frequency aggressive scrapes that would degrade the site for legitimate users

> **Important:** You are responsible for your downstream use. Do not use this dataset to harass owners, scrape personal phone numbers, build "owner finder" tools that expose individuals, or violate VivaReal's ToS in ways that go beyond reasonable analytics and CRM enrichment.

***

### Frequently Asked Questions

#### How fresh is the data?

Live at runtime. VivaReal listings update continuously throughout the day as agents post, edit and remove inventory. Each actor run hits the live site, so what you get is what a Brazilian buyer would see in their browser at that exact moment.

#### How many records can I expect per run?

It depends entirely on your filters. A single hot bairro (e.g., Pinheiros for sale) typically exposes 500–2,000 listings before VivaReal's pagination cap. A full city (e.g., São Paulo, all transactions, all property types) yields tens of thousands. Use `maxRecords` to bound your run.

#### Do I need a VivaReal login or API key?

No. VivaReal does not expose a public API for third parties, and this actor does not need any account credentials. You only need an Apify account.

#### Are Brazilian residential proxies really mandatory?

For any non-trivial volume, yes. VivaReal sits behind Cloudflare bot protection, which actively challenges datacenter IPs and non-BR exit nodes. The default `proxyConfiguration` is set to Apify `RESIDENTIAL` with country preference `BR` — keep it that way unless you have a specific reason to change.

#### Does the actor handle Cloudflare's "Aguarde…" / "Just a moment…" challenge?

Yes. The browser navigation routine polls the page title and waits up to ~30 seconds for the interstitial to clear before parsing. Persistent challenges (proxy is fully burned) cause the task to log a warning and skip — try a fresh run if this happens.

#### Why does my run sometimes return zero listings for a valid-looking URL?

VivaReal silently redirects zero-result searches to a `/showcase/...ERROR...` URL. The actor detects and logs this. Most commonly it means the bairro slug is misspelled, the property type doesn't exist in that bairro, or the price filter excludes everything. Try removing filters and adding them back one at a time.

#### Can I get listing descriptions, amenities and the full photo gallery?

Yes — set `scrapeDetails: true`. The actor will visit each listing page individually and pull description, features, amenities, lat/lng coordinates and the entire image array. Expect 5–10x runtime versus listing-only mode.

#### Does it return phone numbers?

VivaReal hides direct phone numbers behind an "Entrar em contato" click that requires user interaction; the actor does not bypass this. You'll get agency name and CRECI license number when published, but contact details require contacting the publisher directly through VivaReal's flow.

#### How are BRL prices parsed?

The actor's BRL parser correctly handles the Brazilian number format `R$ 1.500.000,50` — dot as thousand separator, comma as decimal. Output `price` is a clean number like `1500000.50`, not a string.

#### What does `condominio` represent — monthly or annual?

Monthly. Condomínio fees in Brazil are universally quoted per month. Multiply by 12 for the annual figure.

#### What does `iptu` represent — monthly or annual?

Annual. IPTU is the municipal property tax assessed once per year (most municipalities allow installment payment over 10 months). VivaReal displays the annual value.

#### What's the difference between `quartos` and `suítes`?

`quartos` = total bedrooms (dormitórios). `suites` is a subset — bedrooms that have an attached private bathroom. A 3 quartos / 1 suíte listing has three bedrooms total, one of which is en-suite.

#### How does FGTS / MCMV / SFH detection work?

The actor scans the listing text for keywords: `FGTS` (severance fund used as down payment), `Minha Casa Minha Vida` / `MCMV` (federal subsidized housing), `SFH` (Sistema Financeiro de Habitação). Detection is best-effort from free text — `true` means it was mentioned, `null` means it wasn't (not necessarily that the listing is ineligible).

#### Does the actor cover both venda (sale) and aluguel (rent)?

Yes. Set `transacao` to `venda`, `aluguel`, `lancamentos`, `temporada`, or `all` (which scrapes both sale and rent in one run).

#### Can I run this on a schedule?

Yes — Apify's built-in Scheduler supports cron expressions. Most users run this daily or weekly per target metro. Daily scheduling lets you compute price-drop and inventory-churn analytics.

#### Does this work with the Apify Free Plan?

Yes — full functionality on the free tier. Small sample runs (e.g., `maxRecords: 50`) typically fit within free-plan compute units; large multi-metro daily scrapes should be on a paid plan for headroom.

#### Can I export to CSV / Excel / XML?

Yes — the Apify dataset view supports JSON, JSONL, CSV, Excel (XLSX), HTML, XML and RSS exports directly. The API also streams JSON Lines for large datasets.

#### What about ZAP Imóveis, OLX Imóveis, Imovelweb?

VivaReal and ZAP Imóveis are sister portals under the same parent (Grupo ZAP / OLX Brasil) but have separate inventory and presentation. Use the **[ZAP Imóveis Scraper](https://apify.com/haketa/zapimoveis-scraper)** for ZAP coverage — see the Related Actors section below.

#### How do I report a bug or request a feature?

Open an issue on the Apify Store actor page, or contact the developer directly through the Apify Console.

#### What happens if VivaReal redesigns its site?

The actor uses a JSON-first extraction path (`__NEXT_DATA__`) with a robust DOM fallback. Most VivaReal redesigns affect CSS class names but leave the Next.js JSON intact, so extraction usually survives without changes. Major schema changes are patched promptly — please open an issue if you spot one.

***

### Related Apify Actors by Haketa

If you work across multiple international real estate portals, these sibling actors share the same input/output conventions:

- [ZAP Imóveis Brazil Scraper](https://apify.com/haketa/zapimoveis-scraper) — VivaReal's sister portal, same group, separate inventory
- [Lamudi Philippines Real Estate Scraper](https://apify.com/haketa/lamudi-scraper) — Southeast Asia property data
- [Zameen.com Pakistan Real Estate Scraper](https://apify.com/haketa/zameen-scraper) — Pakistan's leading property portal
- [Realestate.com.kh Cambodia Scraper](https://apify.com/haketa/realestate-com-kh-scraper) — Cambodia property listings
- [Realtor.ca Canada Property Scraper](https://apify.com/haketa/realtor-ca-scraper) — Canadian MLS data
- [Immoweb.be Belgium Property Scraper](https://apify.com/haketa/immoweb-scraper) — Belgium real estate
- [Domain.com.au Property Scraper](https://apify.com/haketa/domain-com-au-scraper) — Australian residential property
- [Apartments.com Scraper](https://apify.com/haketa/apartments-com-scraper) — US apartment rentals
- [Rent.com Scraper](https://apify.com/haketa/rent-com-scraper) — US rental marketplace

***

### Comparison vs. Alternatives

| Approach | Setup time | Data freshness | Cloudflare handling | BRL price normalization | Bairro geocoding | Cost (1K records) |
|---|---|---|---|---|---|---|
| **This actor** | < 5 minutes | Live at runtime | Built-in | Built-in | Built-in | Cents |
| Manual browsing + copy-paste | Hours | Manual | n/a | Manual | Manual | Labor |
| Custom Playwright DIY | 2–4 weeks | Live, until it breaks | DIY | DIY | DIY | Dev hours + infra |
| Paid real estate API (BR) | Days–weeks contracting | Varies | n/a | Varies | Varies | $500–5,000+/mo |
| Buy a dataset from a broker | Weeks | Stale (monthly snapshots) | n/a | Varies | Varies | $1,000+/dataset |

***

### Why Pay-Per-Event Pricing?

Most scrapers either charge a flat monthly subscription (you pay whether you use it or not) or per-Compute-Unit (unpredictable, browser-heavy actors blow budgets). This actor uses **pay-per-event** pricing instead:

- You pay only when the actor actually runs
- Charges scale with **records delivered**, not with browser wall-clock time
- No monthly minimum — pause for a month, pay zero
- Sampling a new bairro with `maxRecords: 30` costs literal pennies
- Transparent line-item billing inside the Apify Console
- Predictable cost modeling for finance teams — `records × per-event price = total`

***

### Changelog

| Version | Date | Notes |
|---|---|---|
| 1.0.0 | 2026-05 | Initial public release — Playwright Chromium, BRL parser, FGTS/MCMV detection, CRECI extraction, bairro-level geocoding via URL slug parsing, Next.js JSON-first extraction with DOM fallback, residential proxy session rotation, pay-per-event pricing |

***

### Keywords

VivaReal scraper · VivaReal data · vivareal.com.br scraper · Brazil real estate scraper · Brazil property data API · Brasil imóveis API · BRL property price data · São Paulo apartment data · São Paulo apartamento scraper · Rio de Janeiro property scraper · Rio de Janeiro imóveis API · Belo Horizonte real estate data · Brasília property data · Curitiba imóveis scraper · Porto Alegre real estate · Salvador real estate data · Recife property scraper · Fortaleza imóveis API · VivaReal alugar comprar data · IPTU condomínio benchmarking · FGTS MCMV property eligibility · CRECI agent license data · cobertura penthouse Brazil scraper · apartamento residencial scraper · casa em condomínio data · terreno lote Brazil scraper · sala comercial Brazil scraper · Pinheiros real estate data · Vila Madalena scraper · Itaim Bibi property API · Jardins São Paulo scraper · Moema apartment data · Ipanema cobertura scraper · Leblon real estate data · Copacabana property data · Barra da Tijuca scraper · Asa Sul Brasília data · Águas Claras property API · Brazilian real estate analytics · FII fundos imobiliários data · Brazil property investor research · Apify Brazil scraper · Brazilian housing market data · imóveis residenciais Brasil API · imóveis comerciais Brasil scraper · lançamentos imobiliários scraper · temporada vacation rental Brazil

***

### Support

- **Bug reports:** Use the **Issues** tab on the Apify Store actor page
- **Feature requests:** Same place — describe your use case (city, bairro, field, downstream system)
- **Direct contact:** Through the Apify developer profile

If this actor saves you time, a **5-star rating** on the Apify Store helps other Brazilian real estate teams discover it. Obrigado!

# Actor input Schema

## `startUrls` (type: `array`):

Direct VivaReal search URLs. Example: 'https://www.vivareal.com.br/venda/sp/sao-paulo/pinheiros/'

## `transacao` (type: `string`):

Buy, rent, new launches or vacation rental.

## `propertyType` (type: `string`):

Type of property to search.

## `uf` (type: `string`):

Brazilian state code. Examples: 'sp', 'rj', 'mg', 'pr', 'df'. Leave empty for all.

## `cidade` (type: `string`):

City slug. Examples: 'sao-paulo', 'rio-de-janeiro', 'belo-horizonte'. Leave empty for all.

## `bairro` (type: `string`):

Neighborhood slug. Examples: 'pinheiros', 'copacabana', 'itaim-bibi', 'leblon'. Leave empty for all.

## `scrapeDetails` (type: `boolean`):

Visit each listing for full description, amenities, FGTS/MCMV eligibility, CRECI license, coordinates and all images.

## `maxRecords` (type: `integer`):

Maximum total listings. Set 0 for unlimited.

## `maxPages` (type: `integer`):

Maximum pages per search. Set 0 for unlimited.

## `requestDelay` (type: `integer`):

Delay between requests. 2500ms recommended.

## `proxyConfiguration` (type: `object`):

Brazilian RESIDENTIAL proxy strongly recommended. Cloudflare active.

## Actor input object example

```json
{
  "startUrls": [],
  "transacao": "venda",
  "propertyType": "all",
  "scrapeDetails": false,
  "maxRecords": 50,
  "maxPages": 0,
  "requestDelay": 2500,
  "proxyConfiguration": {
    "useApifyProxy": true,
    "apifyProxyGroups": [
      "RESIDENTIAL"
    ]
  }
}
```

# Actor output Schema

## `listingId` (type: `string`):

No description

## `title` (type: `string`):

No description

## `propertyType` (type: `string`):

No description

## `price` (type: `string`):

No description

## `quartos` (type: `string`):

No description

## `bairro` (type: `string`):

No description

## `cidade` (type: `string`):

No description

## `listingUrl` (type: `string`):

No description

## `scrapedAt` (type: `string`):

No description

# 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 = {
    "startUrls": [],
    "transacao": "venda",
    "uf": "",
    "cidade": "",
    "bairro": "",
    "scrapeDetails": false,
    "maxRecords": 50,
    "proxyConfiguration": {
        "useApifyProxy": true,
        "apifyProxyGroups": [
            "RESIDENTIAL"
        ]
    }
};

// Run the Actor and wait for it to finish
const run = await client.actor("haketa/vivareal-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 = {
    "startUrls": [],
    "transacao": "venda",
    "uf": "",
    "cidade": "",
    "bairro": "",
    "scrapeDetails": False,
    "maxRecords": 50,
    "proxyConfiguration": {
        "useApifyProxy": True,
        "apifyProxyGroups": ["RESIDENTIAL"],
    },
}

# Run the Actor and wait for it to finish
run = client.actor("haketa/vivareal-scraper").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 '{
  "startUrls": [],
  "transacao": "venda",
  "uf": "",
  "cidade": "",
  "bairro": "",
  "scrapeDetails": false,
  "maxRecords": 50,
  "proxyConfiguration": {
    "useApifyProxy": true,
    "apifyProxyGroups": [
      "RESIDENTIAL"
    ]
  }
}' |
apify call haketa/vivareal-scraper --silent --output-dataset

```

## MCP server setup

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

```

## OpenAPI specification

```json
{
    "openapi": "3.0.1",
    "info": {
        "title": "VivaReal Scraper | Brazil Real Estate BRL Pricing",
        "description": "Scrape vivareal.com.br, Brazil's top property portal. Apartamentos, casas, coberturas & terrenos. FGTS/MCMV eligibility, CRECI license, IPTU+condomínio, quartos/suítes & bairro location.",
        "version": "0.0",
        "x-build-id": "Ykuy7uU69xm1khEVU"
    },
    "servers": [
        {
            "url": "https://api.apify.com/v2"
        }
    ],
    "paths": {
        "/acts/haketa~vivareal-scraper/run-sync-get-dataset-items": {
            "post": {
                "operationId": "run-sync-get-dataset-items-haketa-vivareal-scraper",
                "x-openai-isConsequential": false,
                "summary": "Executes an Actor, waits for its completion, and returns Actor's dataset items in response.",
                "tags": [
                    "Run Actor"
                ],
                "requestBody": {
                    "required": true,
                    "content": {
                        "application/json": {
                            "schema": {
                                "$ref": "#/components/schemas/inputSchema"
                            }
                        }
                    }
                },
                "parameters": [
                    {
                        "name": "token",
                        "in": "query",
                        "required": true,
                        "schema": {
                            "type": "string"
                        },
                        "description": "Enter your Apify token here"
                    }
                ],
                "responses": {
                    "200": {
                        "description": "OK"
                    }
                }
            }
        },
        "/acts/haketa~vivareal-scraper/runs": {
            "post": {
                "operationId": "runs-sync-haketa-vivareal-scraper",
                "x-openai-isConsequential": false,
                "summary": "Executes an Actor and returns information about the initiated run in response.",
                "tags": [
                    "Run Actor"
                ],
                "requestBody": {
                    "required": true,
                    "content": {
                        "application/json": {
                            "schema": {
                                "$ref": "#/components/schemas/inputSchema"
                            }
                        }
                    }
                },
                "parameters": [
                    {
                        "name": "token",
                        "in": "query",
                        "required": true,
                        "schema": {
                            "type": "string"
                        },
                        "description": "Enter your Apify token here"
                    }
                ],
                "responses": {
                    "200": {
                        "description": "OK",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "$ref": "#/components/schemas/runsResponseSchema"
                                }
                            }
                        }
                    }
                }
            }
        },
        "/acts/haketa~vivareal-scraper/run-sync": {
            "post": {
                "operationId": "run-sync-haketa-vivareal-scraper",
                "x-openai-isConsequential": false,
                "summary": "Executes an Actor, waits for completion, and returns the OUTPUT from Key-value store in response.",
                "tags": [
                    "Run Actor"
                ],
                "requestBody": {
                    "required": true,
                    "content": {
                        "application/json": {
                            "schema": {
                                "$ref": "#/components/schemas/inputSchema"
                            }
                        }
                    }
                },
                "parameters": [
                    {
                        "name": "token",
                        "in": "query",
                        "required": true,
                        "schema": {
                            "type": "string"
                        },
                        "description": "Enter your Apify token here"
                    }
                ],
                "responses": {
                    "200": {
                        "description": "OK"
                    }
                }
            }
        }
    },
    "components": {
        "schemas": {
            "inputSchema": {
                "type": "object",
                "properties": {
                    "startUrls": {
                        "title": "Start URLs",
                        "type": "array",
                        "description": "Direct VivaReal search URLs. Example: 'https://www.vivareal.com.br/venda/sp/sao-paulo/pinheiros/'",
                        "items": {
                            "type": "object",
                            "required": [
                                "url"
                            ],
                            "properties": {
                                "url": {
                                    "type": "string",
                                    "title": "URL of a web page",
                                    "format": "uri"
                                }
                            }
                        }
                    },
                    "transacao": {
                        "title": "Transaction Type",
                        "enum": [
                            "venda",
                            "aluguel",
                            "lancamentos",
                            "temporada",
                            "all"
                        ],
                        "type": "string",
                        "description": "Buy, rent, new launches or vacation rental.",
                        "default": "venda"
                    },
                    "propertyType": {
                        "title": "Property Type",
                        "enum": [
                            "all",
                            "apartamento_residencial",
                            "casa_residencial",
                            "cobertura_residencial",
                            "kitnet_residencial",
                            "studio_residencial",
                            "terreno",
                            "sala_comercial"
                        ],
                        "type": "string",
                        "description": "Type of property to search.",
                        "default": "all"
                    },
                    "uf": {
                        "title": "State (UF)",
                        "type": "string",
                        "description": "Brazilian state code. Examples: 'sp', 'rj', 'mg', 'pr', 'df'. Leave empty for all."
                    },
                    "cidade": {
                        "title": "City",
                        "type": "string",
                        "description": "City slug. Examples: 'sao-paulo', 'rio-de-janeiro', 'belo-horizonte'. Leave empty for all."
                    },
                    "bairro": {
                        "title": "Bairro (Neighborhood)",
                        "type": "string",
                        "description": "Neighborhood slug. Examples: 'pinheiros', 'copacabana', 'itaim-bibi', 'leblon'. Leave empty for all."
                    },
                    "scrapeDetails": {
                        "title": "Scrape Detail Pages",
                        "type": "boolean",
                        "description": "Visit each listing for full description, amenities, FGTS/MCMV eligibility, CRECI license, coordinates and all images.",
                        "default": false
                    },
                    "maxRecords": {
                        "title": "Max Records",
                        "minimum": 0,
                        "type": "integer",
                        "description": "Maximum total listings. Set 0 for unlimited.",
                        "default": 0
                    },
                    "maxPages": {
                        "title": "Max Pages",
                        "minimum": 0,
                        "type": "integer",
                        "description": "Maximum pages per search. Set 0 for unlimited.",
                        "default": 0
                    },
                    "requestDelay": {
                        "title": "Request Delay (ms)",
                        "minimum": 1000,
                        "maximum": 10000,
                        "type": "integer",
                        "description": "Delay between requests. 2500ms recommended.",
                        "default": 2500
                    },
                    "proxyConfiguration": {
                        "title": "Proxy Configuration",
                        "type": "object",
                        "description": "Brazilian RESIDENTIAL proxy strongly recommended. Cloudflare active."
                    }
                }
            },
            "runsResponseSchema": {
                "type": "object",
                "properties": {
                    "data": {
                        "type": "object",
                        "properties": {
                            "id": {
                                "type": "string"
                            },
                            "actId": {
                                "type": "string"
                            },
                            "userId": {
                                "type": "string"
                            },
                            "startedAt": {
                                "type": "string",
                                "format": "date-time",
                                "example": "2025-01-08T00:00:00.000Z"
                            },
                            "finishedAt": {
                                "type": "string",
                                "format": "date-time",
                                "example": "2025-01-08T00:00:00.000Z"
                            },
                            "status": {
                                "type": "string",
                                "example": "READY"
                            },
                            "meta": {
                                "type": "object",
                                "properties": {
                                    "origin": {
                                        "type": "string",
                                        "example": "API"
                                    },
                                    "userAgent": {
                                        "type": "string"
                                    }
                                }
                            },
                            "stats": {
                                "type": "object",
                                "properties": {
                                    "inputBodyLen": {
                                        "type": "integer",
                                        "example": 2000
                                    },
                                    "rebootCount": {
                                        "type": "integer",
                                        "example": 0
                                    },
                                    "restartCount": {
                                        "type": "integer",
                                        "example": 0
                                    },
                                    "resurrectCount": {
                                        "type": "integer",
                                        "example": 0
                                    },
                                    "computeUnits": {
                                        "type": "integer",
                                        "example": 0
                                    }
                                }
                            },
                            "options": {
                                "type": "object",
                                "properties": {
                                    "build": {
                                        "type": "string",
                                        "example": "latest"
                                    },
                                    "timeoutSecs": {
                                        "type": "integer",
                                        "example": 300
                                    },
                                    "memoryMbytes": {
                                        "type": "integer",
                                        "example": 1024
                                    },
                                    "diskMbytes": {
                                        "type": "integer",
                                        "example": 2048
                                    }
                                }
                            },
                            "buildId": {
                                "type": "string"
                            },
                            "defaultKeyValueStoreId": {
                                "type": "string"
                            },
                            "defaultDatasetId": {
                                "type": "string"
                            },
                            "defaultRequestQueueId": {
                                "type": "string"
                            },
                            "buildNumber": {
                                "type": "string",
                                "example": "1.0.0"
                            },
                            "containerUrl": {
                                "type": "string"
                            },
                            "usage": {
                                "type": "object",
                                "properties": {
                                    "ACTOR_COMPUTE_UNITS": {
                                        "type": "integer",
                                        "example": 0
                                    },
                                    "DATASET_READS": {
                                        "type": "integer",
                                        "example": 0
                                    },
                                    "DATASET_WRITES": {
                                        "type": "integer",
                                        "example": 0
                                    },
                                    "KEY_VALUE_STORE_READS": {
                                        "type": "integer",
                                        "example": 0
                                    },
                                    "KEY_VALUE_STORE_WRITES": {
                                        "type": "integer",
                                        "example": 1
                                    },
                                    "KEY_VALUE_STORE_LISTS": {
                                        "type": "integer",
                                        "example": 0
                                    },
                                    "REQUEST_QUEUE_READS": {
                                        "type": "integer",
                                        "example": 0
                                    },
                                    "REQUEST_QUEUE_WRITES": {
                                        "type": "integer",
                                        "example": 0
                                    },
                                    "DATA_TRANSFER_INTERNAL_GBYTES": {
                                        "type": "integer",
                                        "example": 0
                                    },
                                    "DATA_TRANSFER_EXTERNAL_GBYTES": {
                                        "type": "integer",
                                        "example": 0
                                    },
                                    "PROXY_RESIDENTIAL_TRANSFER_GBYTES": {
                                        "type": "integer",
                                        "example": 0
                                    },
                                    "PROXY_SERPS": {
                                        "type": "integer",
                                        "example": 0
                                    }
                                }
                            },
                            "usageTotalUsd": {
                                "type": "number",
                                "example": 0.00005
                            },
                            "usageUsd": {
                                "type": "object",
                                "properties": {
                                    "ACTOR_COMPUTE_UNITS": {
                                        "type": "integer",
                                        "example": 0
                                    },
                                    "DATASET_READS": {
                                        "type": "integer",
                                        "example": 0
                                    },
                                    "DATASET_WRITES": {
                                        "type": "integer",
                                        "example": 0
                                    },
                                    "KEY_VALUE_STORE_READS": {
                                        "type": "integer",
                                        "example": 0
                                    },
                                    "KEY_VALUE_STORE_WRITES": {
                                        "type": "number",
                                        "example": 0.00005
                                    },
                                    "KEY_VALUE_STORE_LISTS": {
                                        "type": "integer",
                                        "example": 0
                                    },
                                    "REQUEST_QUEUE_READS": {
                                        "type": "integer",
                                        "example": 0
                                    },
                                    "REQUEST_QUEUE_WRITES": {
                                        "type": "integer",
                                        "example": 0
                                    },
                                    "DATA_TRANSFER_INTERNAL_GBYTES": {
                                        "type": "integer",
                                        "example": 0
                                    },
                                    "DATA_TRANSFER_EXTERNAL_GBYTES": {
                                        "type": "integer",
                                        "example": 0
                                    },
                                    "PROXY_RESIDENTIAL_TRANSFER_GBYTES": {
                                        "type": "integer",
                                        "example": 0
                                    },
                                    "PROXY_SERPS": {
                                        "type": "integer",
                                        "example": 0
                                    }
                                }
                            }
                        }
                    }
                }
            }
        }
    }
}
```