# VivaReal Scraper — Brazil Real Estate Listings (`bgfc97/vivareal-imoveis-scraper`) Actor

🔥 Up to 30% OFF! Scrape VivaReal real-estate listings — no login. By city+filters, search URL or property URL: price, condo fee, IPTU, area, bedrooms/baths/suites/parking, amenities, full address+CEP, GPS, images, realtor (CRECI). Great for real-estate research. ⚡

- **URL**: https://apify.com/bgfc97/vivareal-imoveis-scraper.md
- **Developed by:** [Bruno](https://apify.com/bgfc97) (community)
- **Categories:** Real estate, Business
- **Stats:** 2 total users, 1 monthly users, 100.0% runs succeeded, 0 bookmarks
- **User rating**: No ratings yet

## Pricing

from $0.84 / 1,000 property scrapeds

This Actor is paid per event and usage. You are charged both the fixed price for specific events and for Apify platform usage.
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 Imóveis Scraper

Extract Brazilian real-estate listings from **[VivaReal](https://www.vivareal.com.br)** (Grupo OLX /
ZAP) as clean, structured JSON — by **city**, by **filters**, or by pasting a **VivaReal search URL**.
Built for lead generation, market intelligence, price monitoring, and analytics pipelines.

No browser. No login. No cookies. **Public data only.**

### Why this one

- **Richest fields in the niche** — price, condo fee (condomínio), yearly IPTU, the full address
  *with latitude/longitude*, property type, bedrooms, bathrooms, suites, parking spaces, usable &
  total area, the complete amenity list (raw codes **and** human-readable PT-BR labels), description,
  all image URLs, the advertiser (name, license/CRECI, phones), and publish/update dates.
- **Three ways to ask** — a simple City (+ optional State), structured filters, or just paste the
  VivaReal results URL you already built on the site.
- **Reliable** — talks to VivaReal's own JSON backend over an anti-blocking proxy that clears the
  Cloudflare challenge server-side; every request retries with a fresh session and falls back
  automatically if it gets challenged.
- **Cheap** — plain HTTP (no headless browser), small JSON pages.

### Input

| Field | Type | Notes |
|-------|------|-------|
| `searchUrls` | string\[] | VivaReal results URLs (paginated) and/or single-property URLs (`…/imovel/…-id-123/`). Filters are read from the URL. |
| `city` | string | City to search when no URL is given, e.g. `São Paulo`. A neighborhood works too (`Jardins, São Paulo`). |
| `state` | string | Optional, to disambiguate the city (`SP`, `Minas Gerais`, …). |
| `transactionType` | enum | `sale` (venda) or `rent` (aluguel). Default `sale`. |
| `propertyType` | enum\[] | `apartment`, `house`, `condo`, `land`, `commercial`, `farm`. Empty = all. |
| `listingType` | enum | `used` (resale) or `development` (lançamento). |
| `priceMin` / `priceMax` | integer | Price range in R$ (sale price or monthly rent). |
| `minBedrooms` | integer | Minimum bedrooms. |
| `maxItems` | integer | Max properties to return (default 100). |
| `imageWidth` / `imageHeight` | integer | Pixel size of the resolved image URLs (default 870×653). |
| `proxyConfiguration` | object | Advanced. Defaults to Apify Proxy `UNBLOCKER`. |

Provide **either** `searchUrls` **or** `city`. Both can be combined.

#### Example

```json
{
  "city": "São Paulo",
  "transactionType": "sale",
  "propertyType": ["apartment"],
  "priceMin": 400000,
  "priceMax": 900000,
  "minBedrooms": 2,
  "maxItems": 200
}
```

### Output

One item per property:

```json
{
  "type": "property",
  "id": "2878742279",
  "url": "https://www.vivareal.com.br/imovel/id-2878742279/",
  "title": "Apartamento com 2 quartos à venda...",
  "description": "...",
  "businessType": "SALE",
  "transactionType": "sale",
  "listingType": "USED",
  "propertyType": "apartment",
  "unitTypes": ["APARTMENT"],
  "price": 685000,
  "currency": "BRL",
  "condoFee": 650,
  "iptu": 2400,
  "rentPeriod": null,
  "rentTotalPrice": null,
  "area": 83,
  "usableAreas": [83],
  "bedrooms": 2,
  "bathrooms": 2,
  "suites": 1,
  "parkingSpaces": 1,
  "amenities": ["POOL", "BARBECUE_GRILL", "ELEVATOR"],
  "amenitiesLabeled": ["Piscina", "Churrasqueira", "Elevador"],
  "address": {
    "street": "Rua ...", "streetNumber": "590", "neighborhood": "Vila Dom Pedro I",
    "zone": "Zona Sul", "city": "São Paulo", "state": "São Paulo",
    "stateAcronym": "SP", "zipCode": "04276000", "country": "BR"
  },
  "latitude": -23.59887,
  "longitude": -46.613918,
  "images": ["https://resizedimgs.vivareal.com/.../imovel.jpg?action=fit-in&dimension=870x653"],
  "imagesCount": 12,
  "advertiser": {
    "id": "0b6e...", "name": "Imobiliária X", "licenseNumber": "CRECI 12345",
    "phone": "1135786452", "mobile": "11953284350"
  },
  "publishedAt": "2024-01-05T04:59:32.546+00:00",
  "updatedAt": "2024-09-...",
  "scrapedAt": "2026-10-05T...Z"
}
```

For rentals, `price` is the monthly rent and `rentTotalPrice` includes condo fee + IPTU when VivaReal
provides it.

### How it works

VivaReal serves its listing data from a JSON backend (`glue-api.vivareal.com`). The actor resolves
your location through VivaReal's own location autocomplete, then pages that backend (24 listings per
page) over **Apify Proxy's `UNBLOCKER` group**, which solves VivaReal's Cloudflare anti-bot challenge
on the proxy side and returns clean JSON over a plain HTTPS GET — no headless browser and no
captcha-solving key. Single-property URLs are fetched as rendered HTML (also via UNBLOCKER) and parsed
from the page's embedded structured data.

### Notes & limits

- VivaReal exposes up to ~10,000 results per individual search. To pull a larger market, split by
  neighborhood, price band, or property type.
- Only public listing data is returned. The actor never logs in and never uses cookies.

# Actor input Schema

## `searchUrls` (type: `array`):

Paste one or more VivaReal URLs. A search-results URL (e.g. https://www.vivareal.com.br/venda/sp/sao-paulo/apartamento_residencial/ ) is paginated for all matching listings. A property URL (…/imovel/…-id-123456/ ) returns that single property. Filters (business, property type, location) are read straight from the URL. Leave empty to use the City/State fields below.

## `city` (type: `string`):

City to search, e.g. "São Paulo", "Rio de Janeiro", "Belo Horizonte". Used when no search URL is given. The actor resolves it to VivaReal's exact location automatically. You can also type a neighborhood (e.g. "Jardins, São Paulo").

## `state` (type: `string`):

Optional state to disambiguate the city, e.g. "SP", "RJ", "Minas Gerais".

## `transactionType` (type: `string`):

Sale (venda) or Rent (aluguel). Applies to City/State searches.

## `propertyType` (type: `array`):

Restrict to one or more property types. Leave empty for all types. (Applies to City/State searches; a search URL carries its own type.)

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

Used/resale properties or new developments (lançamentos).

## `priceMin` (type: `integer`):

Minimum price in BRL (sale price, or monthly rent for rentals). Leave empty for no minimum.

## `priceMax` (type: `integer`):

Maximum price in BRL. Leave empty for no maximum.

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

Only listings with at least this many bedrooms. Leave empty for any.

## `maxItems` (type: `integer`):

Maximum number of property records to return across all searches (1–100000). VivaReal exposes up to ~10,000 results per individual search; narrow with filters to reach the rest.

## `imageWidth` (type: `integer`):

Width of the resolved image URLs returned per listing. Default 870.

## `imageHeight` (type: `integer`):

Height of the resolved image URLs. Default 653.

## `timeoutSecs` (type: `integer`):

How long to wait for each request to VivaReal, in seconds (15–180). The anti-blocking proxy solves the Cloudflare challenge server-side, so requests can take a few seconds.

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

Advanced. By default the actor uses Apify Proxy's UNBLOCKER group, which clears VivaReal's Cloudflare anti-bot challenge server-side over plain HTTP (no browser, no captcha key) — this is what makes the scrape reliable. Override only if you know what you are doing; the actor still falls back to UNBLOCKER if your proxy gets challenged.

## Actor input object example

```json
{
  "searchUrls": [
    "https://www.vivareal.com.br/venda/sp/sao-paulo/apartamento_residencial/"
  ],
  "city": "São Paulo",
  "transactionType": "sale",
  "propertyType": [],
  "listingType": "used",
  "maxItems": 100,
  "imageWidth": 870,
  "imageHeight": 653,
  "timeoutSecs": 60,
  "proxyConfiguration": {
    "useApifyProxy": true,
    "apifyProxyGroups": [
      "UNBLOCKER"
    ]
  }
}
```

# Actor output Schema

# API

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

## JavaScript example

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

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

// Prepare Actor input
const input = {
    "searchUrls": [
        "https://www.vivareal.com.br/venda/sp/sao-paulo/apartamento_residencial/"
    ],
    "proxyConfiguration": {
        "useApifyProxy": true,
        "apifyProxyGroups": [
            "UNBLOCKER"
        ]
    }
};

// Run the Actor and wait for it to finish
const run = await client.actor("bgfc97/vivareal-imoveis-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 = {
    "searchUrls": ["https://www.vivareal.com.br/venda/sp/sao-paulo/apartamento_residencial/"],
    "proxyConfiguration": {
        "useApifyProxy": True,
        "apifyProxyGroups": ["UNBLOCKER"],
    },
}

# Run the Actor and wait for it to finish
run = client.actor("bgfc97/vivareal-imoveis-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 '{
  "searchUrls": [
    "https://www.vivareal.com.br/venda/sp/sao-paulo/apartamento_residencial/"
  ],
  "proxyConfiguration": {
    "useApifyProxy": true,
    "apifyProxyGroups": [
      "UNBLOCKER"
    ]
  }
}' |
apify call bgfc97/vivareal-imoveis-scraper --silent --output-dataset

```

## MCP server setup

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