# VivaReal Brazil Real Estate Scraper | Property Listings API (`scrapers_lat/vivareal-scraper`) Actor

Scrape VivaReal Brazil property listings for sale and rent (imoveis a venda e aluguel). Get price, condo fee, IPTU, area, bedrooms, address, GPS, photos, amenities and advertiser contacts (phone, WhatsApp, CRECI). Filter by city, price, type, bedrooms. Export JSON, CSV, Excel. Run via API.

- **URL**: https://apify.com/scrapers_lat/vivareal-scraper.md
- **Developed by:** [Scrapers Lat](https://apify.com/scrapers_lat) (community)
- **Categories:** Real estate, Automation, Developer tools
- **Features:** Limited permissions
- **Stats:** 4 total users, 1 monthly users, 100.0% runs succeeded, 0 bookmarks
- **User rating**: No ratings yet

## Pricing

from $11.35 / 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/actors/running/actors-in-store.md#pay-per-event

## What's an Apify Actor?

An Actor is a serverless cloud program that runs on the Apify platform. It has two run modes.
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.

Apify vocabulary and the platform model are defined once, in the agent quickstart at https://apify.com/agents.md.

## 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.

Do not guess an integration path. Every one of them is in the agent quickstart at https://apify.com/agents.md: the Apify MCP server, Agent Skills with the Apify CLI, the JavaScript and Python clients, the REST API, and the account-free path for an agent with no human to sign in. It also carries the rule on stating cost before the first paid run.

For examples already wired to this Actor's own input schema, see the [API](#api) section below.

Each client library has reference documentation the quickstart does not restate: [JavaScript/TypeScript](https://docs.apify.com/api/client/js/docs.md) (`npm install apify-client`) and [Python](https://docs.apify.com/api/client/python/docs.md) (`pip install apify-client`).

# README

[![VivaReal Brazil Real Estate Scraper](https://scrapers.lat/banners/vivareal-scraper.png)](https://console.apify.com/actors/Icn8ebXebCaCErF40/input)

## VivaReal Brazil Real Estate Scraper | Property Listings & Imoveis API

Scrape **VivaReal Brazil** (vivareal.com.br, Grupo ZAP / OLX) property listings for **sale and rent** (imoveis a venda e aluguel) and export clean, structured **Brazil real estate data**: price, condominio fee, IPTU, area, bedrooms, bathrooms, address, GPS coordinates, photos, amenities and full **advertiser contacts** (phone, WhatsApp, CRECI license). Search by city, neighborhood, or a VivaReal URL, filter exactly what you need, and pull results as JSON, CSV or Excel, or run it via API.

Here is one real result, with every field the actor returns (`images` and `amenities` trimmed for space; all other values are exactly as returned):

```json
{
  "listingId": "2718283450",
  "externalId": "01014",
  "title": "Apartamento a venda com 65m², 2 dormitorios e 1 vaga no Condominio Ideal",
  "url": "https://www.vivareal.com.br/imovel/apartamento-2-quartos-cambuci-zona-sul-sao-paulo-com-garagem-65m2-venda-RS595000-id-2718283450/",
  "imageUrl": "https://resizedimgs.vivareal.com/img/vr-listing/63159dab.../crop.jpg?action=&dimension=870x653",
  "price": 595000,
  "currency": "BRL",
  "condoFee": 441,
  "iptu": 890,
  "totalMonthlyPrice": null,
  "pricePerM2": 9153.85,
  "showPrice": true,
  "acceptExchange": false,
  "operationType": "venda",
  "propertyType": "APARTMENT",
  "usageType": "RESIDENTIAL",
  "listingType": "USED",
  "publicationType": "PREMIUM",
  "isDevelopment": false,
  "isHighlighted": true,
  "constructionStatus": "ConstructionStatus_NONE",
  "bedrooms": 2,
  "bathrooms": 1,
  "suites": 0,
  "parkingSpaces": 1,
  "usableAreaM2": 65,
  "totalAreaM2": 65,
  "floors": 13,
  "unitFloor": 1,
  "unitsOnTheFloor": 4,
  "neighborhood": "Cambuci",
  "city": "Sao Paulo",
  "state": "Sao Paulo",
  "stateAcronym": "SP",
  "zone": "Centro",
  "street": "Rua Dona Ana Neri",
  "streetNumber": "581",
  "zipCode": "01522000",
  "latitude": -23.559503,
  "longitude": -46.615471,
  "advertiser": "Santucci Broker Negocios Imobiliarios",
  "advertiserId": "577d7ddd-6a3a-e2a3-b3da-31a3916c371c",
  "advertiserLegacyId": "287555",
  "advertiserType": "AGENCY",
  "advertiserTier": "gold",
  "advertiserVerified": true,
  "advertiserCreci": "31016-J-SP",
  "advertiserSince": "2018-03-28T04:58:41Z",
  "advertiserUrl": "https://www.vivareal.com.br/imobiliaria/287555/",
  "advertiserLogo": "https://resizedimgs.vivareal.com/img/vr-listing/7af24518.../crop.jpg?action=&dimension=300x300",
  "advertiserPhone": "11999782608",
  "advertiserWhatsapp": "11999782608",
  "videoTourLink": "https://my.matterport.com/show/?m=XTbnhrm",
  "publishedAt": "2024-05-29T20:07:12.572Z",
  "updatedAt": "2026-08-26T17:47:06.754Z",
  "description": "Apartamento finamente reformado, decorado, a venda no Cambuci com 2 dormitorios...",
  "amenities": ["POOL", "GYM", "ELEVATOR", "PARTY_HALL", "GATED_COMMUNITY", "BARBECUE_GRILL"],
  "images": ["https://resizedimgs.vivareal.com/img/vr-listing/63159dab.../crop.jpg?action=&dimension=870x653"],
  "observedAt": "2026-09-04T22:51:59.827Z",
  "error": null
}
```

The most complete **VivaReal scraper** available: it returns every field the listing card and detail page expose, plus derived fields like `pricePerM2`, `totalMonthlyPrice` and `advertiserType`, and lets you search by location or URL with filters for operation, property type, price, bedrooms, bathrooms, parking, area and amenities so you target exactly the listings you need.

**📥 [Input](https://apify.com/scrapers_lat/vivareal-scraper/input-schema) · 📤 [Output](https://apify.com/scrapers_lat/vivareal-scraper/output-schema) · 💰 [Pricing](https://apify.com/scrapers_lat/vivareal-scraper/pricing) · ▶️ [Examples](https://apify.com/scrapers_lat/vivareal-scraper/examples)**

![Apify](https://img.shields.io/badge/Platform-Apify-1CE1CE?logo=apify\&logoColor=white)
![Coverage](https://img.shields.io/badge/Coverage-Brazil-blue)
![Output](https://img.shields.io/badge/Output-JSON%20%7C%20CSV%20%7C%20Excel-orange)
![Billing](https://img.shields.io/badge/Billing-Pay%20per%20result-brightgreen)

### Table of contents

- [What it does](#what-it-does)
- [Why this scraper](#why-this-scraper)
- [Quickstart](#quickstart)
- [Input reference](#input-reference)
- [Output reference](#output-reference)
- [Comparison with other VivaReal scrapers](#comparison-with-other-vivareal-scrapers)
- [Use cases](#use-cases)
- [Run via API and CLI](#run-via-api-and-cli)
- [Fetch results](#fetch-results)
- [Billing and limits](#billing-and-limits)
- [FAQ and troubleshooting](#faq-and-troubleshooting)

### What it does

The actor searches **VivaReal Brazil** by location (or a search URL you paste), paginates through the results, and writes one normalized record per property listing to the run's dataset. Prices are parsed into a numeric `price` plus `currency`; monthly `condoFee` and yearly `iptu` are separated out; area and price are combined into `pricePerM2` for valuation; and the location is split into `neighborhood`, `city`, `state`, `stateAcronym`, `zone`, `street`, `streetNumber`, `zipCode` and GPS `latitude`/`longitude`. With `withDetails` enabled, each listing is enriched with the full `description`, complete `images` gallery and `amenities` list.

Data covers VivaReal Brazil property listings only (sale and rent, used and new developments). You control coverage with the location or a search URL, and the filters below.

### Why this scraper

- **Every field, honest nulls.** Card and detail fields in one pass: price breakdown (price, condo fee, IPTU, total monthly), area, rooms, floor, exact address, coordinates, advertiser identity and contacts.
- **Advertiser intelligence.** `advertiserType` (agency / developer / owner), `advertiserTier`, `advertiserVerified`, `advertiserCreci` (real-estate license), `advertiserSince`, plus direct `advertiserPhone` and `advertiserWhatsapp` for lead generation.
- **Valuation ready.** `pricePerM2` and `totalMonthlyPrice` (rent + condo + IPTU) computed for you.
- **Precise targeting.** Filter by city, operation, property type, price range, bedrooms, bathrooms, parking, area range and amenities.
- **Flexible input.** A plain city name, or paste any VivaReal search URL, or batch many with filters.

### Quickstart

Open the actor, paste this into the input, and press Run. It returns 10 apartments for sale in Sao Paulo, enriched with advertiser contacts and coordinates.

```json
{
  "searchTerm": "Sao Paulo",
  "business": "SALE",
  "unitType": "APARTMENT",
  "maxListings": 10,
  "withDetails": true
}
```

Every field is optional except a location or URL. Pass a `startUrl` to reuse a filtered VivaReal search URL (it overrides the location and operation fields), or set `business` to `RENTAL` for rentals.

### Input reference

| Field | Type | Required | Default | Description |
|---|---|---|---|---|
| `searchTerm` | string | yes\* | `Sao Paulo` | City or neighborhood to search, for example `Sao Paulo`, `Rio de Janeiro`, `Copacabana`. Resolved automatically to the matching VivaReal location. |
| `startUrl` | string | yes\* | (none) | A VivaReal search results URL. The location, operation, and property type are read from the URL and override the filter fields. |
| `business` | enum | no | `SALE` | Operation: `SALE` (venda) or `RENTAL` (aluguel). |
| `listingType` | enum | no | `USED` | `USED` (resale) or `DEVELOPMENT` (new developments). |
| `unitType` | enum | no | `APARTMENT` | Property type: `APARTMENT`, `HOME`, `PENTHOUSE`, `ALLOTMENT_LAND`, `FARM`, `RESIDENTIAL_BUILDING`, or `ANY`. |
| `maxListings` | integer | no | `10` | Maximum number of listings to collect. |
| `withDetails` | boolean | no | `true` | When enabled, each listing also includes description, full image gallery and amenities (paying plans). |
| `minPrice` / `maxPrice` | integer | no | (none) | Price range in BRL. |
| `minBedrooms` / `maxBedrooms` | integer | no | (none) | Bedroom range. |
| `minBathrooms` | integer | no | (none) | Minimum bathrooms. |
| `minParking` | integer | no | (none) | Minimum parking spaces. |
| `minArea` / `maxArea` | integer | no | (none) | Usable area range in square metres. |
| `amenities` | string\[] | no | (none) | Only return listings that have ALL of these amenity codes (e.g. `POOL`, `GYM`, `ELEVATOR`). |

\*One of `searchTerm` or `startUrl` is required.

### Output reference

One dataset item per listing. Types: `string`, `number`, `boolean`, `string[]`, or `null` when the source value is absent.

| Field | Type | Description |
|---|---|---|
| `listingId` | string | VivaReal listing ID (deduplication key). |
| `externalId` | string | Advertiser reference / external ID. |
| `url` | string | Full URL of the listing detail page. |
| `title` | string | Listing title. |
| `price` | number | Asking price (sale) or monthly rent (rental). |
| `currency` | string | Currency of the price (`BRL`). |
| `condoFee` | number | Monthly condominium fee (BRL). |
| `iptu` | number | Yearly property tax, IPTU (BRL). |
| `totalMonthlyPrice` | number | All-in monthly cost for rentals (rent + condo + IPTU), or `null` for sales. |
| `pricePerM2` | number | Price per usable square metre (BRL). |
| `showPrice` | boolean | Whether the price is publicly shown. |
| `acceptExchange` | boolean | Whether the seller accepts a property exchange (permuta). |
| `operationType` | string | `venda` (sale) or `aluguel` (rent). |
| `propertyType` | string | Property type (`APARTMENT`, `HOME`, `PENTHOUSE`, and so on). |
| `propertySubType` | string | Property sub-type, when present. |
| `usageType` | string | `RESIDENTIAL` or `COMMERCIAL`. |
| `listingType` | string | `USED` (resale) or `DEVELOPMENT` (new). |
| `publicationType` | string | Publication tier (`STANDARD`, `PREMIUM`, `SUPER_PREMIUM`). |
| `isDevelopment` | boolean | True for new-development listings. |
| `isHighlighted` | boolean | True for premium / highlighted listings. |
| `constructionStatus` | string | Construction status. |
| `bedrooms` | number | Number of bedrooms. |
| `bathrooms` | number | Number of bathrooms. |
| `suites` | number | Number of en-suite bedrooms. |
| `parkingSpaces` | number | Number of parking spaces. |
| `usableAreaM2` | number | Usable area in square metres. |
| `totalAreaM2` | number | Total area in square metres. |
| `floors` | number | Number of floors in the building. |
| `unitFloor` | number | Floor the unit is on (0 = ground floor). |
| `unitsOnTheFloor` | number | Units per floor. |
| `condominiumName` | string | Condominium / building name. |
| `neighborhood` | string | Neighborhood / bairro. |
| `city` | string | City. |
| `state` | string | Brazilian state. |
| `stateAcronym` | string | State acronym (e.g. `SP`). |
| `zone` | string | City zone (for example `Zona Oeste`). |
| `street` | string | Street name. |
| `streetNumber` | string | Street number. |
| `zipCode` | string | Postal code (CEP). |
| `latitude` | number | GPS latitude. |
| `longitude` | number | GPS longitude. |
| `advertiser` | string | Advertiser / agency name. |
| `advertiserId` | string | Advertiser account ID. |
| `advertiserLegacyId` | string | Advertiser legacy VivaReal ID. |
| `advertiserType` | string | `AGENCY`, `DEVELOPER`, or `OWNER`. |
| `advertiserTier` | string | Advertiser subscription tier. |
| `advertiserVerified` | boolean | Whether the advertiser is verified. |
| `advertiserCreci` | string | Advertiser CRECI real-estate license number. |
| `advertiserSince` | string | Advertiser account creation date. |
| `advertiserWebsite` | string | Advertiser website URL. |
| `advertiserUrl` | string | Advertiser profile URL on VivaReal. |
| `advertiserLogo` | string | Advertiser logo image URL. |
| `advertiserPhone` | string | Advertiser phone. |
| `advertiserWhatsapp` | string | Advertiser WhatsApp / mobile. |
| `videoTourLink` | string | Video tour URL, when present. |
| `imageUrl` | string | Primary listing image URL. |
| `images` | string\[] | Full image gallery URLs (detail). |
| `amenities` | string\[] | Amenity codes (detail). |
| `description` | string | Listing description text (detail). |
| `publishedAt` | string | Publication timestamp. |
| `updatedAt` | string | Last update timestamp. |
| `observedAt` | string | ISO 8601 timestamp of when the record was collected. |
| `error` | string | `null` on success. On a failed run, a single item with a populated `error` field is written instead. |

### Comparison with other VivaReal scrapers

| Capability | This actor | fatihtahta/vivareal-scraper | gio21/vivareal-zap-scraper | stealth_mode/vivareal-property-search |
|---|---|---|---|---|
| Search by city / neighborhood | Yes | Yes | Yes | No (URL only) |
| Search by VivaReal URL | Yes | No | No | Yes |
| Filter operation / type | Yes | Yes | No | No |
| Filters: price, beds, baths, parking, area | Yes | Yes | No | No |
| Filter by amenities | Yes | Yes | No | No |
| Price + condo fee + IPTU split | Yes | Partial | No | Partial |
| `totalMonthlyPrice` (all-in rent) | Yes | No | No | No |
| `pricePerM2` | Yes | No | No | No |
| GPS coordinates | Yes | Partial | No | Partial |
| Advertiser phone + WhatsApp | Yes | Partial | No | Partial |
| Advertiser type / tier / verified / CRECI | Yes | No | No | No |
| Full image gallery + amenities | Yes | Partial | Partial | Partial |
| No charge on failure / spend cap | Yes | Varies | Varies | Varies |

This actor accepts every input the listed competitors accept and returns a strict superset of their output fields, adding the price breakdown, `totalMonthlyPrice`, `pricePerM2`, advertiser identity block (type, tier, verified, CRECI) and full contacts.

### Use cases

- **Real estate lead generation** in Brazil: harvest agency and owner phone, WhatsApp and CRECI license from live listings.
- **Market and price analysis**: track `pricePerM2`, condo fees and asking prices by city, neighborhood and zone.
- **Property portals and aggregators**: feed a search index of imoveis a venda e aluguel with clean, deduplicated records.
- **Investment sourcing**: filter by area, price and amenities to find undervalued apartamentos e casas.
- **CRM enrichment**: attach coordinates, images and advertiser identity to your existing pipeline.

### Run via API and CLI

Start a run and wait for it to finish, then read the dataset. Replace `<TOKEN>` with your Apify API token.

Run synchronously and get dataset items in one call:

```bash
curl -X POST "https://api.apify.com/v2/acts/scrapers_lat~vivareal-scraper/run-sync-get-dataset-items?token=<TOKEN>" \
  -H "Content-Type: application/json" \
  -d '{"searchTerm":"Sao Paulo","business":"SALE","unitType":"APARTMENT","maxListings":25,"withDetails":true}'
```

Start a run asynchronously:

```bash
curl -X POST "https://api.apify.com/v2/acts/scrapers_lat~vivareal-scraper/runs?token=<TOKEN>" \
  -H "Content-Type: application/json" \
  -d '{"startUrl":"https://www.vivareal.com.br/venda/sp/sao-paulo/apartamento_residencial/","maxListings":100}'
```

Apify CLI:

```bash
apify call scrapers_lat/vivareal-scraper \
  --input '{"searchTerm":"Rio de Janeiro","business":"RENTAL","maxListings":20}'
```

### Fetch results

Every run writes to a dataset. Fetch items as JSON, CSV, or Excel by changing `format`:

```bash
## JSON
curl "https://api.apify.com/v2/datasets/<DATASET_ID>/items?token=<TOKEN>&clean=true&format=json"

## CSV
curl "https://api.apify.com/v2/datasets/<DATASET_ID>/items?token=<TOKEN>&clean=true&format=csv"

## Paginate large datasets
curl "https://api.apify.com/v2/datasets/<DATASET_ID>/items?token=<TOKEN>&offset=1000&limit=1000"
```

`<DATASET_ID>` is returned as `defaultDatasetId` in the run object.

### Billing and limits

- **Pay per result.** You are charged per record returned (`result` event). With `withDetails` a per-record `details` event covers the description, full gallery and amenities. See the [pricing tab](https://apify.com/scrapers_lat/vivareal-scraper/pricing) for current prices.
- **No charge on failure.** If a run errors, the actor writes a single item with a populated `error` field and does not charge for it. Empty runs cost nothing.
- **Spend cap respected.** Set `maxTotalChargeUsd` on the run; once reached, the actor stops emitting and charging further billable results.
- **Free Apify plans** are capped at 10 records per run and receive card-level records only. Upgrade for higher `maxListings` and detail enrichment.
- **Source pagination ceiling.** VivaReal caps deep pagination; very large single searches end when the source stops returning pages. Split with tighter filters or separate locations for bigger pulls.

### FAQ and troubleshooting

**A run returned 0 records. Why?**
The location did not resolve, or the filters removed everything. Confirm the `searchTerm` matches a real VivaReal location, or paste a working `startUrl`, and loosen price/bedroom/area filters. Zero-result runs are not charged.

**How do I get advertiser phone numbers and coordinates?**
Coordinates and advertiser phone / WhatsApp are on every record. Keep `withDetails` enabled to also get the full description, image gallery and amenities.

**Can I reuse a filtered search from the website?**
Yes. Copy the VivaReal search URL after applying your filters and pass it as `startUrl`. It overrides the location, operation, and property-type fields.

**Why is `totalMonthlyPrice` null?**
That field only applies to rentals (rent + condo + IPTU). For sale listings it is `null`. Missing values are returned as `null`, never invented.

**What is `pricePerM2`?**
The price divided by the usable area, in BRL. It is the standard comparable metric for valuing property against similar listings.

**Is this an official VivaReal tool?**
No. This actor is independent and has no affiliation with VivaReal or Grupo ZAP. It reads only data that is publicly available on the website.

### Related scrapers

- [ZAP Imoveis Brazil Real Estate Scraper](https://apify.com/scrapers_lat/zap-scraper): the sibling ZAP portal, same Brazil coverage.
- [QuintoAndar Brazil Real Estate Scraper](https://apify.com/scrapers_lat/quintoandar-scraper): Brazil rentals and sales from QuintoAndar.
- [OLX Brazil Scraper](https://apify.com/scrapers_lat/olx-brazil-scraper): Brazil classifieds including real estate.
- [Inmuebles24 Mexico Real Estate Scraper](https://apify.com/scrapers_lat/inmuebles24-scraper): Mexico property listings and agent contacts.
- [AdondeVivir Peru Real Estate Scraper](https://apify.com/scrapers_lat/adondevivir-scraper): Peru property listings.

### More scrapers at scrapers.lat

Built and maintained by [scrapers.lat](https://scrapers.lat), where we publish scrapers for US and Latin American public platforms: company registries, government data, finance, e-commerce and more. Browse the catalog or request a custom scraper at [scrapers.lat](https://scrapers.lat).

> Independent tool, not affiliated with VivaReal. Accesses only publicly available listing data.

***

## Raspador de Imoveis VivaReal Brasil | API de Anuncios e Imoveis

Extraia anuncios de imoveis do **VivaReal Brasil** (vivareal.com.br, Grupo ZAP / OLX) para **venda e aluguel** (imoveis a venda e aluguel) e exporte **dados imobiliarios do Brasil** limpos e estruturados: preco, condominio, IPTU, area, quartos, banheiros, endereco, coordenadas GPS, fotos, comodidades e **contatos do anunciante** (telefone, WhatsApp, CRECI). Busque por cidade, bairro ou uma URL do VivaReal, filtre exatamente o que precisa e baixe os resultados em JSON, CSV ou Excel, ou rode via API.

Veja um resultado real, com todos os campos que o ator retorna (`images` e `amenities` reduzidos por espaco; os demais valores sao exatamente como retornados):

```json
{
  "listingId": "2718283450",
  "externalId": "01014",
  "title": "Apartamento a venda com 65m², 2 dormitorios e 1 vaga no Condominio Ideal",
  "url": "https://www.vivareal.com.br/imovel/apartamento-2-quartos-cambuci-zona-sul-sao-paulo-com-garagem-65m2-venda-RS595000-id-2718283450/",
  "price": 595000,
  "currency": "BRL",
  "condoFee": 441,
  "iptu": 890,
  "pricePerM2": 9153.85,
  "operationType": "venda",
  "propertyType": "APARTMENT",
  "listingType": "USED",
  "publicationType": "PREMIUM",
  "bedrooms": 2,
  "bathrooms": 1,
  "suites": 0,
  "parkingSpaces": 1,
  "usableAreaM2": 65,
  "unitFloor": 1,
  "neighborhood": "Cambuci",
  "city": "Sao Paulo",
  "state": "Sao Paulo",
  "zone": "Centro",
  "zipCode": "01522000",
  "latitude": -23.559503,
  "longitude": -46.615471,
  "advertiser": "Santucci Broker Negocios Imobiliarios",
  "advertiserType": "AGENCY",
  "advertiserTier": "gold",
  "advertiserVerified": true,
  "advertiserCreci": "31016-J-SP",
  "advertiserPhone": "11999782608",
  "advertiserWhatsapp": "11999782608",
  "amenities": ["POOL", "GYM", "ELEVATOR", "PARTY_HALL", "GATED_COMMUNITY", "BARBECUE_GRILL"],
  "observedAt": "2026-09-04T22:51:59.827Z",
  "error": null
}
```

O **raspador do VivaReal** mais completo disponivel: retorna todos os campos do card e da pagina de detalhe, mais campos derivados como `pricePerM2`, `totalMonthlyPrice` e `advertiserType`, e permite buscar por localizacao ou URL com filtros de operacao, tipo de imovel, preco, quartos, banheiros, vagas, area e comodidades para focar exatamente nos anuncios que voce precisa.

**📥 [Entrada](https://apify.com/scrapers_lat/vivareal-scraper/input-schema) · 📤 [Saida](https://apify.com/scrapers_lat/vivareal-scraper/output-schema) · 💰 [Precos](https://apify.com/scrapers_lat/vivareal-scraper/pricing) · ▶️ [Exemplos](https://apify.com/scrapers_lat/vivareal-scraper/examples)**

### Indice

- [O que faz](#o-que-faz)
- [Por que este raspador](#por-que-este-raspador)
- [Inicio rapido](#inicio-rapido)
- [Referencia de entrada](#referencia-de-entrada)
- [Referencia de saida](#referencia-de-saida)
- [Comparacao com outros raspadores do VivaReal](#comparacao-com-outros-raspadores-do-vivareal)
- [Casos de uso](#casos-de-uso)
- [Rodar via API e CLI](#rodar-via-api-e-cli)
- [Baixar resultados](#baixar-resultados)
- [Cobranca e limites](#cobranca-e-limites)
- [FAQ e solucao de problemas](#faq-e-solucao-de-problemas)

### O que faz

O ator busca no **VivaReal Brasil** por localizacao (ou uma URL de busca que voce cola), pagina pelos resultados e grava um registro normalizado por anuncio no dataset da execucao. O preco e convertido em `price` numerico mais `currency`; o `condoFee` mensal e o `iptu` anual sao separados; area e preco sao combinados em `pricePerM2` para avaliacao; e a localizacao e dividida em `neighborhood`, `city`, `state`, `stateAcronym`, `zone`, `street`, `streetNumber`, `zipCode` e coordenadas GPS `latitude`/`longitude`. Com `withDetails` ativado, cada anuncio e enriquecido com a `description` completa, a galeria `images` inteira e a lista de `amenities`.

Os dados cobrem apenas anuncios do VivaReal Brasil (venda e aluguel, usados e lancamentos). Voce controla a cobertura com a localizacao ou uma URL de busca, e os filtros abaixo.

### Por que este raspador

- **Todos os campos, nulos honestos.** Campos do card e do detalhe em uma so passada: preco detalhado (preco, condominio, IPTU, total mensal), area, comodos, andar, endereco exato, coordenadas, identidade e contatos do anunciante.
- **Inteligencia do anunciante.** `advertiserType` (imobiliaria / construtora / proprietario), `advertiserTier`, `advertiserVerified`, `advertiserCreci` (licenca imobiliaria), `advertiserSince`, mais `advertiserPhone` e `advertiserWhatsapp` diretos para geracao de leads.
- **Pronto para avaliacao.** `pricePerM2` e `totalMonthlyPrice` (aluguel + condominio + IPTU) calculados para voce.
- **Segmentacao precisa.** Filtre por cidade, operacao, tipo de imovel, faixa de preco, quartos, banheiros, vagas, faixa de area e comodidades.
- **Entrada flexivel.** Um nome de cidade, ou cole qualquer URL de busca do VivaReal, ou processe varias com filtros.

### Inicio rapido

Abra o ator, cole isto na entrada e clique em Run. Retorna 10 apartamentos a venda em Sao Paulo, com contatos do anunciante e coordenadas.

```json
{
  "searchTerm": "Sao Paulo",
  "business": "SALE",
  "unitType": "APARTMENT",
  "maxListings": 10,
  "withDetails": true
}
```

Todos os campos sao opcionais, exceto uma localizacao ou URL. Passe um `startUrl` para reutilizar uma URL de busca filtrada do VivaReal (ela sobrepoe os campos de localizacao e operacao), ou defina `business` como `RENTAL` para aluguel.

### Referencia de entrada

| Campo | Tipo | Obrigatorio | Padrao | Descricao |
|---|---|---|---|---|
| `searchTerm` | string | sim\* | `Sao Paulo` | Cidade ou bairro para buscar, por exemplo `Sao Paulo`, `Rio de Janeiro`, `Copacabana`. Resolvido automaticamente para a localizacao do VivaReal. |
| `startUrl` | string | sim\* | (nenhum) | Uma URL de resultados de busca do VivaReal. Localizacao, operacao e tipo de imovel sao lidos da URL e sobrepoem os filtros. |
| `business` | enum | nao | `SALE` | Operacao: `SALE` (venda) ou `RENTAL` (aluguel). |
| `listingType` | enum | nao | `USED` | `USED` (revenda) ou `DEVELOPMENT` (lancamentos). |
| `unitType` | enum | nao | `APARTMENT` | Tipo de imovel: `APARTMENT`, `HOME`, `PENTHOUSE`, `ALLOTMENT_LAND`, `FARM`, `RESIDENTIAL_BUILDING` ou `ANY`. |
| `maxListings` | integer | nao | `10` | Numero maximo de anuncios a coletar. |
| `withDetails` | boolean | nao | `true` | Quando ativo, cada anuncio tambem inclui descricao, galeria completa e comodidades (planos pagos). |
| `minPrice` / `maxPrice` | integer | nao | (nenhum) | Faixa de preco em BRL. |
| `minBedrooms` / `maxBedrooms` | integer | nao | (nenhum) | Faixa de quartos. |
| `minBathrooms` | integer | nao | (nenhum) | Minimo de banheiros. |
| `minParking` | integer | nao | (nenhum) | Minimo de vagas de garagem. |
| `minArea` / `maxArea` | integer | nao | (nenhum) | Faixa de area util em metros quadrados. |
| `amenities` | string\[] | nao | (nenhum) | Retorna apenas anuncios que tenham TODOS estes codigos de comodidade (ex.: `POOL`, `GYM`, `ELEVATOR`). |

\*Um de `searchTerm` ou `startUrl` e obrigatorio.

### Referencia de saida

Um item de dataset por anuncio. Tipos: `string`, `number`, `boolean`, `string[]` ou `null` quando o valor de origem esta ausente.

| Campo | Tipo | Descricao |
|---|---|---|
| `listingId` | string | ID do anuncio no VivaReal (chave de deduplicacao). |
| `externalId` | string | Referencia do anunciante / ID externo. |
| `url` | string | URL completa da pagina do anuncio. |
| `title` | string | Titulo do anuncio. |
| `price` | number | Preco de venda ou aluguel mensal. |
| `currency` | string | Moeda do preco (`BRL`). |
| `condoFee` | number | Taxa de condominio mensal (BRL). |
| `iptu` | number | IPTU anual (BRL). |
| `totalMonthlyPrice` | number | Custo mensal total para aluguel (aluguel + condominio + IPTU), ou `null` para venda. |
| `pricePerM2` | number | Preco por metro quadrado util (BRL). |
| `showPrice` | boolean | Se o preco e exibido publicamente. |
| `acceptExchange` | boolean | Se o vendedor aceita permuta. |
| `operationType` | string | `venda` ou `aluguel`. |
| `propertyType` | string | Tipo de imovel (`APARTMENT`, `HOME`, `PENTHOUSE`, etc.). |
| `propertySubType` | string | Subtipo de imovel, quando presente. |
| `usageType` | string | `RESIDENTIAL` ou `COMMERCIAL`. |
| `listingType` | string | `USED` (revenda) ou `DEVELOPMENT` (novo). |
| `publicationType` | string | Nivel de publicacao (`STANDARD`, `PREMIUM`, `SUPER_PREMIUM`). |
| `isDevelopment` | boolean | Verdadeiro para lancamentos. |
| `isHighlighted` | boolean | Verdadeiro para anuncios premium / destacados. |
| `constructionStatus` | string | Status de construcao. |
| `bedrooms` | number | Numero de quartos. |
| `bathrooms` | number | Numero de banheiros. |
| `suites` | number | Numero de suites. |
| `parkingSpaces` | number | Numero de vagas de garagem. |
| `usableAreaM2` | number | Area util em metros quadrados. |
| `totalAreaM2` | number | Area total em metros quadrados. |
| `floors` | number | Numero de andares do predio. |
| `unitFloor` | number | Andar da unidade (0 = terreo). |
| `unitsOnTheFloor` | number | Unidades por andar. |
| `condominiumName` | string | Nome do condominio / predio. |
| `neighborhood` | string | Bairro. |
| `city` | string | Cidade. |
| `state` | string | Estado. |
| `stateAcronym` | string | Sigla do estado (ex.: `SP`). |
| `zone` | string | Zona da cidade (ex.: `Zona Oeste`). |
| `street` | string | Nome da rua. |
| `streetNumber` | string | Numero. |
| `zipCode` | string | CEP. |
| `latitude` | number | Latitude GPS. |
| `longitude` | number | Longitude GPS. |
| `advertiser` | string | Nome do anunciante / imobiliaria. |
| `advertiserId` | string | ID da conta do anunciante. |
| `advertiserLegacyId` | string | ID legado do anunciante no VivaReal. |
| `advertiserType` | string | `AGENCY`, `DEVELOPER` ou `OWNER`. |
| `advertiserTier` | string | Nivel de assinatura do anunciante. |
| `advertiserVerified` | boolean | Se o anunciante e verificado. |
| `advertiserCreci` | string | Numero de licenca CRECI do anunciante. |
| `advertiserSince` | string | Data de criacao da conta do anunciante. |
| `advertiserWebsite` | string | Site do anunciante. |
| `advertiserUrl` | string | URL do perfil do anunciante no VivaReal. |
| `advertiserLogo` | string | URL do logo do anunciante. |
| `advertiserPhone` | string | Telefone do anunciante. |
| `advertiserWhatsapp` | string | WhatsApp / celular do anunciante. |
| `videoTourLink` | string | URL do tour em video, quando presente. |
| `imageUrl` | string | URL da imagem principal. |
| `images` | string\[] | URLs da galeria completa (detalhe). |
| `amenities` | string\[] | Codigos de comodidades (detalhe). |
| `description` | string | Texto da descricao do anuncio (detalhe). |
| `publishedAt` | string | Data de publicacao. |
| `updatedAt` | string | Data da ultima atualizacao. |
| `observedAt` | string | Data ISO 8601 da coleta do registro. |
| `error` | string | `null` em caso de sucesso. Em falha, um unico item com `error` preenchido e gravado. |

### Comparacao com outros raspadores do VivaReal

| Recurso | Este ator | fatihtahta/vivareal-scraper | gio21/vivareal-zap-scraper | stealth_mode/vivareal-property-search |
|---|---|---|---|---|
| Busca por cidade / bairro | Sim | Sim | Sim | Nao (so URL) |
| Busca por URL do VivaReal | Sim | Nao | Nao | Sim |
| Filtro de operacao / tipo | Sim | Sim | Nao | Nao |
| Filtros: preco, quartos, banheiros, vagas, area | Sim | Sim | Nao | Nao |
| Filtro por comodidades | Sim | Sim | Nao | Nao |
| Preco + condominio + IPTU separados | Sim | Parcial | Nao | Parcial |
| `totalMonthlyPrice` (aluguel total) | Sim | Nao | Nao | Nao |
| `pricePerM2` | Sim | Nao | Nao | Nao |
| Coordenadas GPS | Sim | Parcial | Nao | Parcial |
| Telefone + WhatsApp do anunciante | Sim | Parcial | Nao | Parcial |
| Tipo / nivel / verificado / CRECI do anunciante | Sim | Nao | Nao | Nao |
| Galeria completa + comodidades | Sim | Parcial | Parcial | Parcial |
| Sem cobranca em falha / limite de gasto | Sim | Varia | Varia | Varia |

Este ator aceita todas as entradas que os concorrentes listados aceitam e retorna um superconjunto estrito dos campos de saida deles, adicionando o preco detalhado, `totalMonthlyPrice`, `pricePerM2`, o bloco de identidade do anunciante (tipo, nivel, verificado, CRECI) e contatos completos.

### Casos de uso

- **Geracao de leads imobiliarios** no Brasil: colete telefone, WhatsApp e CRECI de imobiliarias e proprietarios a partir de anuncios ao vivo.
- **Analise de mercado e precos**: acompanhe `pricePerM2`, condominio e precos por cidade, bairro e zona.
- **Portais e agregadores de imoveis**: alimente um indice de imoveis a venda e aluguel com registros limpos e deduplicados.
- **Prospeccao de investimentos**: filtre por area, preco e comodidades para achar apartamentos e casas subavaliados.
- **Enriquecimento de CRM**: anexe coordenadas, imagens e identidade do anunciante ao seu pipeline.

### Rodar via API e CLI

Inicie uma execucao, aguarde terminar e leia o dataset. Substitua `<TOKEN>` pelo seu token da API da Apify.

Rodar de forma sincrona e obter os itens em uma chamada:

```bash
curl -X POST "https://api.apify.com/v2/acts/scrapers_lat~vivareal-scraper/run-sync-get-dataset-items?token=<TOKEN>" \
  -H "Content-Type: application/json" \
  -d '{"searchTerm":"Sao Paulo","business":"SALE","unitType":"APARTMENT","maxListings":25,"withDetails":true}'
```

Iniciar de forma assincrona:

```bash
curl -X POST "https://api.apify.com/v2/acts/scrapers_lat~vivareal-scraper/runs?token=<TOKEN>" \
  -H "Content-Type: application/json" \
  -d '{"startUrl":"https://www.vivareal.com.br/venda/sp/sao-paulo/apartamento_residencial/","maxListings":100}'
```

Apify CLI:

```bash
apify call scrapers_lat/vivareal-scraper \
  --input '{"searchTerm":"Rio de Janeiro","business":"RENTAL","maxListings":20}'
```

### Baixar resultados

Cada execucao grava em um dataset. Baixe os itens em JSON, CSV ou Excel mudando `format`:

```bash
## JSON
curl "https://api.apify.com/v2/datasets/<DATASET_ID>/items?token=<TOKEN>&clean=true&format=json"

## CSV
curl "https://api.apify.com/v2/datasets/<DATASET_ID>/items?token=<TOKEN>&clean=true&format=csv"

## Paginar datasets grandes
curl "https://api.apify.com/v2/datasets/<DATASET_ID>/items?token=<TOKEN>&offset=1000&limit=1000"
```

`<DATASET_ID>` e retornado como `defaultDatasetId` no objeto da execucao.

### Cobranca e limites

- **Pagamento por resultado.** Voce e cobrado por registro retornado (evento `result`). Com `withDetails`, um evento `details` por registro cobre a descricao, a galeria completa e as comodidades. Veja a [aba de precos](https://apify.com/scrapers_lat/vivareal-scraper/pricing).
- **Sem cobranca em falha.** Se a execucao falhar, o ator grava um unico item com `error` preenchido e nao cobra por ele. Execucoes vazias nao custam nada.
- **Limite de gasto respeitado.** Defina `maxTotalChargeUsd` na execucao; ao atingir o limite, o ator para de emitir e cobrar resultados.
- **Planos gratuitos da Apify** sao limitados a 10 registros por execucao e recebem apenas registros de nivel card. Faca upgrade para `maxListings` maior e enriquecimento de detalhes.
- **Limite de paginacao da origem.** O VivaReal limita a paginacao profunda; buscas muito grandes terminam quando a origem para de retornar paginas. Divida com filtros mais restritos ou localizacoes separadas.

### FAQ e solucao de problemas

**Uma execucao retornou 0 registros. Por que?**
A localizacao nao foi resolvida, ou os filtros removeram tudo. Confirme que o `searchTerm` corresponde a uma localizacao real do VivaReal, ou cole uma `startUrl` valida, e afrouxe os filtros de preco/quarto/area. Execucoes com zero resultados nao sao cobradas.

**Como obtenho telefones do anunciante e coordenadas?**
Coordenadas e telefone / WhatsApp do anunciante estao em cada registro. Mantenha `withDetails` ativo para tambem obter a descricao completa, a galeria de imagens e as comodidades.

**Posso reutilizar uma busca filtrada do site?**
Sim. Copie a URL de busca do VivaReal apos aplicar seus filtros e passe como `startUrl`. Ela sobrepoe os campos de localizacao, operacao e tipo de imovel.

**Por que `totalMonthlyPrice` esta null?**
Esse campo so se aplica a aluguel (aluguel + condominio + IPTU). Para venda ele e `null`. Valores ausentes sao retornados como `null`, nunca inventados.

**O que e `pricePerM2`?**
O preco dividido pela area util, em BRL. E a metrica comparavel padrao para avaliar imoveis semelhantes.

**Esta e uma ferramenta oficial do VivaReal?**
Nao. Este ator e independente e nao tem afiliacao com o VivaReal ou o Grupo ZAP. Le apenas dados publicamente disponiveis no site.

### Mais raspadores em scrapers.lat

Construido e mantido pela [scrapers.lat](https://scrapers.lat), onde publicamos raspadores para plataformas publicas dos EUA e da America Latina: registros de empresas, dados governamentais, financas, e-commerce e mais. Navegue pelo catalogo ou solicite um raspador sob medida em [scrapers.lat](https://scrapers.lat).

> Ferramenta independente, sem afiliacao com o VivaReal. Acessa apenas dados de anuncios publicamente disponiveis.

# Actor input Schema

## `maxListings` (type: `integer`):

Maximum number of listings to collect. Optional.

## `withDetails` (type: `boolean`):

When enabled, each listing also includes description, amenities, all images, advertiser and coordinates.

## `searchTerm` (type: `string`):

City or neighborhood to search on VivaReal, e.g. "Sao Paulo", "Rio de Janeiro", "Copacabana". Resolved automatically to the matching VivaReal location.

## `startUrl` (type: `string`):

Optional. A VivaReal search results URL (e.g. https://www.vivareal.com.br/venda/sp/sao-paulo/apartamento_residencial/). The location, operation and property type are read from the URL and override the fields below.

## `business` (type: `string`):

Buy (venda) or rent (aluguel).

## `listingType` (type: `string`):

Used (resale) properties or new developments.

## `unitType` (type: `string`):

Type of property to search for.

## `minPrice` (type: `integer`):

Optional. Only return listings priced at or above this amount (Brazilian Reais).

## `maxPrice` (type: `integer`):

Optional. Only return listings priced at or below this amount (Brazilian Reais).

## `minBedrooms` (type: `integer`):

Optional. Only return listings with at least this many bedrooms.

## `maxBedrooms` (type: `integer`):

Optional. Only return listings with at most this many bedrooms.

## `minBathrooms` (type: `integer`):

Optional. Only return listings with at least this many bathrooms.

## `minParking` (type: `integer`):

Optional. Only return listings with at least this many parking spaces.

## `minArea` (type: `integer`):

Optional. Only return listings with at least this usable area in square metres.

## `maxArea` (type: `integer`):

Optional. Only return listings with at most this usable area in square metres.

## `amenities` (type: `array`):

Optional. Only return listings that have ALL of these amenity codes, e.g. POOL, GYM, ELEVATOR, BARBECUE_GRILL, GATED_COMMUNITY, PLAYGROUND, PARTY_HALL.

## Actor input object example

```json
{
  "maxListings": 10,
  "withDetails": true,
  "searchTerm": "Sao Paulo",
  "business": "SALE",
  "listingType": "USED",
  "unitType": "APARTMENT"
}
```

# Actor output Schema

## `results` (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 = {
    "maxListings": 10,
    "searchTerm": "Sao Paulo"
};

// Run the Actor and wait for it to finish
const run = await client.actor("scrapers_lat/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 = {
    "maxListings": 10,
    "searchTerm": "Sao Paulo",
}

# Run the Actor and wait for it to finish
run = client.actor("scrapers_lat/vivareal-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 '{
  "maxListings": 10,
  "searchTerm": "Sao Paulo"
}' |
apify call scrapers_lat/vivareal-scraper --silent --output-dataset

```

## MCP server setup

```json
{
    "mcpServers": {
        "apify": {
            "type": "http",
            "url": "https://mcp.apify.com/?tools=fetch-actor-details,scrapers_lat/vivareal-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/Icn8ebXebCaCErF40/builds/SKEMeNOmjceJS8k7k/openapi.json