# VivaReal Scraper - Brazil Real Estate Imoveis (`logiover/vivareal-scraper`) Actor

VivaReal imoveis scraper and unofficial API alternative. Export Brazil real estate listings to CSV/JSON: price, condo fee, IPTU, area, beds and geo. No login.

- **URL**: https://apify.com/logiover/vivareal-scraper.md
- **Developed by:** [Logiover](https://apify.com/logiover) (community)
- **Categories:** Real estate, E-commerce, AI
- **Features:** Limited permissions
- **Stats:** 64 total users, 1 monthly users, 100.0% runs succeeded, 0 bookmarks
- **User rating**: No ratings yet

## Pricing

from $1.99 / 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 Scraper — Brazil Real Estate (Imóveis) Listings, Prices & Leads (No API)

![Apify Actor](https://img.shields.io/badge/Apify-Actor-00A67E?logo=apify\&logoColor=white) ![No API key](https://img.shields.io/badge/No%20API%20key-required-2ea44f) ![Pay per result](https://img.shields.io/badge/Pricing-Pay%20per%20result-1C7ED6) ![Real Estate](https://img.shields.io/badge/Category-Real%20Estate-8B5CF6) ![Export](https://img.shields.io/badge/Export-JSON%20%7C%20CSV%20%7C%20Excel-F59E0B)

Extract property listings (**imóveis**) from **VivaReal**, one of Brazil's largest real-estate portals (Grupo OLX / ZAP), for **sale (venda)** or **rent (aluguel)** — apartments, houses, land, commercial, farms and penthouses. Get **price, condominium fee, IPTU, usable area, bedrooms, full address, exact GPS coordinates, photos and advertiser details** in clean structured JSON. Point it at a city or paste a `vivareal.com.br` search URL and it **paginates to pull thousands of listings across Brazil — no login, no API key.**

> ### 🏆 Why this VivaReal scraper?
>
> **30+ fields per listing** · **thousands of imóveis per run** · builder mode *or* raw search-URL mode · condo fee + IPTU + GPS + agent · export to JSON / CSV / Excel. The unofficial **VivaReal API alternative** for Brazilian real-estate market analysis, valuation comps and lead generation.

***

### ✨ What this Actor does / Key features

- 🏠 **6 property types** — apartments, houses, land/lots, commercial, farms/country and penthouses, for **sale or rent**.
- 🔗 **Two ways to target** — paste one or more `vivareal.com.br` search URLs (location, operation, type and price parsed automatically), or use the **builder** with city, state, operation, type and filters.
- 💰 **Full Brazilian cost breakdown** — `price` (BRL), monthly `condoFee`, `iptu` and `yearlyIptu` (property tax), so you can model true total monthly cost.
- 🛏️ **Property details** — `bedrooms`, `bathrooms`, `suites`, `parkingSpaces`, `usableAreaM2` and `totalAreaM2`.
- 📍 **Full address & GPS** — nested `address` with neighborhood, zone, city, state, ZIP and full address, plus exact `lat` / `lng` coordinates for mapping.
- 🏢 **Advertiser lead data** — nested `advertiser` with agency/owner name, license number, phone and logo.
- 🖼️ **Media** — `images` gallery and `videoTourLink` when available.
- 🎛️ **Powerful filters** — price range (BRL), min bedrooms, used/resale vs new-development listing type, and per-neighborhood `locationId` targeting.
- 🛡️ **Proxy support** — VivaReal data is served from Brazil; the Actor defaults to Apify Proxy · **RESIDENTIAL** · country **BR** for reliable access.

### 🚀 Quick start (3 steps)

1. **Configure** — either paste a `vivareal.com.br` search URL, or set **City**, **Operation** (sale/rent) and **Property type** in the builder. Add price/bedroom filters if you want.
2. **Run** — click **Start**. The Actor paginates the results and streams listings into your dataset.
3. **Get your data** — open the **Output** tab and export to **JSON, CSV, Excel or XML**, or pull it via the Apify API.

### 📥 Input

Use **either** `searchUrls` **or** the builder fields (`city` + `operationType` + `propertyType`). Everything else is optional.

#### Example — apartments for sale in São Paulo (builder mode)

```json
{
  "operationType": "SALE",
  "propertyType": "APARTMENT",
  "listingType": "USED",
  "city": "São Paulo",
  "state": "São Paulo",
  "minPrice": 300000,
  "maxPrice": 1200000,
  "minBedrooms": 2,
  "maxResults": 1000,
  "proxyConfiguration": { "useApifyProxy": true, "apifyProxyGroups": ["RESIDENTIAL"], "apifyProxyCountry": "BR" }
}
```

#### Example — rentals in Rio de Janeiro (builder mode)

```json
{
  "operationType": "RENTAL",
  "propertyType": "APARTMENT",
  "city": "Rio de Janeiro",
  "state": "Rio de Janeiro",
  "minBedrooms": 1,
  "maxResults": 500,
  "proxyConfiguration": { "useApifyProxy": true, "apifyProxyGroups": ["RESIDENTIAL"], "apifyProxyCountry": "BR" }
}
```

#### Example — paste a VivaReal search URL directly

```json
{
  "searchUrls": [
    "https://www.vivareal.com.br/venda/sp/sao-paulo/apartamento_residencial/"
  ],
  "maxResults": 800
}
```

| Field | Type | Description |
|-------|------|-------------|
| `searchUrls` | array | One or more `vivareal.com.br` search/result URLs. Location, operation, type and price filters are derived from each URL. Leave empty to use the builder. |
| `operationType` | string | `SALE` (venda) or `RENTAL` (aluguel). Builder mode. |
| `listingType` | string | `USED` (resale) or `DEVELOPMENT` (new launches). |
| `propertyType` | string | `APARTMENT`, `HOME`, `ALLOTMENT_LAND`, `BUSINESS`, `FARM`, `PENTHOUSE` or blank for all. |
| `city` / `state` | string | City / state name in Portuguese (e.g. `São Paulo`, `Rio de Janeiro`). Builder mode. |
| `locationId` | string | Advanced: precise VivaReal `locationId` to target a neighborhood; overrides city/state. |
| `minPrice` / `maxPrice` | integer | Price range in BRL. |
| `minBedrooms` | integer | Minimum number of bedrooms. |
| `maxResults` | integer | Total listings to collect across all searches. A single query returns up to ~1,476 listings; add more cities/URLs to reach more. Default `1000`. |
| `proxyConfiguration` | object | Apify Proxy settings. Default RESIDENTIAL · country BR is strongly recommended. |

> **Finding a search URL:** browse vivareal.com.br, apply your location, operation and filters, and copy the resulting URL into `searchUrls`. A single filter set caps around ~1,476 listings, so add more cities, neighborhoods (`locationId`) or URLs to reach deeper inventory.

### 📤 Output

One row per listing — **30+ fields** with nested `address`, `advertiser` and `images`, exportable to JSON, CSV, Excel or XML. Here is a trimmed sample record:

```json
{
  "id": "2718281828",
  "title": "Apartamento 2 dormitórios à venda em Pinheiros",
  "operationType": "SALE",
  "listingType": "USED",
  "propertyType": "APARTMENT",
  "unitSubTypes": ["UnitSubType_APARTMENT"],
  "price": 890000,
  "condoFee": 1200,
  "iptu": 380,
  "yearlyIptu": 4560,
  "currency": "BRL",
  "bedrooms": 2,
  "bathrooms": 2,
  "suites": 1,
  "parkingSpaces": 1,
  "usableAreaM2": 68,
  "totalAreaM2": 72,
  "address": {
    "street": "Rua dos Pinheiros",
    "streetNumber": "500",
    "neighborhood": "Pinheiros",
    "zone": "Zona Oeste",
    "city": "São Paulo",
    "state": "São Paulo",
    "stateAcronym": "SP",
    "zipCode": "05422-001",
    "fullAddress": "Rua dos Pinheiros, 500 - Pinheiros, São Paulo - SP"
  },
  "lat": -23.5629,
  "lng": -46.6825,
  "amenities": ["ELEVATOR", "GYM", "…"],
  "description": "Excelente apartamento reformado, próximo ao metrô…",
  "advertiser": {
    "name": "Imobiliária Premium",
    "licenseNumber": "CRECI 12345-J",
    "phone": "+5511999999999",
    "logo": "https://resizedimgs.vivareal.com/…/logo.png"
  },
  "images": ["https://resizedimgs.vivareal.com/…/1.jpg", "…"],
  "videoTourLink": null,
  "url": "https://www.vivareal.com.br/imovel/…-id-2718281828/",
  "listingUrl": "https://www.vivareal.com.br/imovel/…-id-2718281828/",
  "portal": "VIVAREAL",
  "publicationType": "PREMIUM",
  "createdAt": "2026-06-28T10:15:00Z",
  "updatedAt": "2026-07-02T08:00:00Z",
  "scrapedAt": "2026-07-06T12:00:00.000Z"
}
```

<details>
<summary><b>📋 Full field reference (click to expand)</b></summary>

| Field | Description |
|-------|-------------|
| `id` | VivaReal listing ID |
| `title` | Listing headline |
| `operationType` | `SALE` (venda) or `RENTAL` (aluguel) |
| `listingType` | `USED` (resale) or `DEVELOPMENT` (new launch) |
| `propertyType` / `unitSubTypes` | Property type and sub-types |
| `price` | Price in BRL |
| `condoFee` | Monthly condominium fee (BRL) |
| `iptu` / `yearlyIptu` | Property tax (IPTU), monthly / yearly (BRL) |
| `currency` | Currency code (BRL) |
| `bedrooms` / `bathrooms` / `suites` / `parkingSpaces` | Room and parking counts |
| `usableAreaM2` / `totalAreaM2` | Usable and total area in m² |
| `address.street` / `streetNumber` / `neighborhood` / `zone` / `city` / `state` / `stateAcronym` / `zipCode` / `fullAddress` | Nested address breakdown |
| `lat` / `lng` | GPS coordinates |
| `amenities` | Amenity codes |
| `description` | Listing description |
| `advertiser.name` / `licenseNumber` / `phone` / `logo` | Nested advertiser / agency lead data |
| `images` | Image gallery URLs |
| `videoTourLink` | Video tour link when available |
| `url` / `listingUrl` | Direct link to the VivaReal listing |
| `portal` / `publicationType` | Source portal and publication tier |
| `createdAt` / `updatedAt` | Listing dates |
| `scrapedAt` | Scrape timestamp (ISO 8601) |

</details>

### 💡 Use cases

- **Brazil real-estate market analysis** — track price, price-per-m², condo fees and IPTU across cities, zones and neighborhoods.
- **Valuation & comparables** — assemble comps by neighborhood with area, beds, `usableAreaM2` and full address.
- **Imóveis lead generation** — collect `advertiser` names and phones for agency/owner outreach lists.
- **Investor deal sourcing** — filter by price, bedrooms and property type to surface rentals or resale opportunities.
- **Rental-yield modeling** — combine sale prices with rental listings for the same area to estimate gross yield.
- **Mapping & dashboards** — feed geo-coded `lat` / `lng` listings into a GIS map or BI dashboard.

### 👥 Who uses it

Brazilian real-estate agencies & imobiliárias · proptech teams · property investors & flippers · valuation and mortgage analysts · market researchers & data journalists · lead-gen agencies building advertiser contact lists.

### 💰 Pricing

This Actor runs on a simple **pay-per-result** model — you pay for the listings you extract, with no separate Apify platform fees to calculate. Try it on the **free tier** first, then scale up. See the **Pricing** tab on this page for the current rate.

### ❓ Frequently Asked Questions

**Is this a VivaReal API alternative?**
Yes. VivaReal has no open public listings API, so this Actor works as an unofficial **VivaReal API alternative** — it reads public imóveis pages and returns structured records (price, area, IPTU, geo, advertiser) you can query on a schedule via the Apify API.

**Can I scrape VivaReal without an API or login?**
Yes. This is a no-login VivaReal data extraction tool. It reads only public listing pages through Brazilian residential proxies, so you never need a VivaReal account, cookies or API key — only an Apify account.

**Do I need a proxy?**
Yes, effectively. VivaReal data is served from Brazil, so the Actor defaults to Apify Proxy · **RESIDENTIAL** · country **BR** for reliable access. Keep the default for best results.

**Can I scrape both rentals and properties for sale?**
Yes. Set `operationType` to `SALE` (venda) or `RENTAL` (aluguel), and optionally choose `USED` (resale) or `DEVELOPMENT` (new launch) via `listingType`.

**Does it include condo fees and IPTU?**
Yes. Every record includes `condoFee` (monthly condominium fee) and `iptu` / `yearlyIptu` (property tax) alongside the `price` in BRL, so you can model total monthly cost.

**How much data can I get?**
Thousands of listings per run. A single filter set caps around ~1,476 listings, so combine multiple cities, neighborhoods (`locationId`) or search URLs to reach deeper inventory across Brazil.

**How do I export VivaReal data to CSV or JSON?**
Run the Actor, then download the dataset as **CSV, JSON, Excel or XML** from the Run tab, or pull it through the Apify API. Every imóvel becomes one row with price, area, IPTU and geo fields.

**Is scraping VivaReal legal?**
This Actor collects only publicly available listing data. You are responsible for using it in line with VivaReal's terms and applicable laws (such as Brazil's LGPD for personal data like advertiser details). Use it responsibly.

### 🔗 More real estate scrapers by logiover

Building a cross-country property dataset? Pair VivaReal with the rest of the international real-estate suite:

| Country | Actor |
|---|---|
| 🇧🇷 Brazil | **VivaReal Scraper** (this Actor) |
| 🇵🇱 Poland | [Otodom.pl Scraper](https://apify.com/logiover/otodom-pl-scraper-polish-real-estate-data) |
| 🇪🇸 Spain | [Habitaclia Scraper](https://apify.com/logiover/habitaclia-com-spain-scraper) · [Pisos.com Scraper](https://apify.com/logiover/pisos-com-property-scraper) |
| 🇨🇿 Czechia | [Sreality.cz Scraper](https://apify.com/logiover/sreality-cz-scraper-czech-real-estate-data) |
| 🇬🇷 Greece | [Spitogatos Scraper](https://apify.com/logiover/spitogatos-gr-real-estate-scraper-greece-properties-data) · [XE.gr Scraper](https://apify.com/logiover/xe-gr-real-estate-scraper-greece-property-data) |
| 🇮🇹 Italy | [Casa.it Scraper](https://apify.com/logiover/casa-it-scraper-italy-real-estate) · [Subito Scraper](https://apify.com/logiover/subito-it-property-scraper) |
| 🇩🇪 Germany | [ImmobilienScout24 Scraper](https://apify.com/logiover/immobilienscout24-de-scraper-germany-real-estate) · [WG-Gesucht Scraper](https://apify.com/logiover/wg-gesucht-scraper) |
| 🇵🇹 Portugal | [Imovirtual Scraper](https://apify.com/logiover/imovirtual-pt-scraper-portugal-real-estate) |
| 🇫🇷 France | [Bien'ici Scraper](https://apify.com/logiover/bien-ici-fr-scraper-france-real-estate) |
| 🇷🇴 Romania | [Storia.ro Scraper](https://apify.com/logiover/storia-ro-scraper-romania-real-estate) |
| 🇳🇱 Netherlands | [Funda Scraper](https://apify.com/logiover/funda-scraper) |
| 🇮🇪 Ireland | [MyHome.ie Scraper](https://apify.com/logiover/myhome-ie-scraper) |
| 🇦🇹 Austria | [Willhaben Scraper](https://apify.com/logiover/willhaben-at-scraper) |
| 🇺🇸 USA | [Realtor.com Scraper](https://apify.com/logiover/realtor-com-scraper) · [Redfin Scraper](https://apify.com/logiover/redfin-scraper) |

👉 Browse all **[logiover scrapers on Apify Store](https://apify.com/logiover)** — 180+ actors across real estate, jobs, crypto, social media & B2B data.

### ⏰ Scheduling & integration

Schedule this Actor on Apify to track the Brazilian property market daily or weekly. Export results to JSON, CSV or Excel, sync to **Google Sheets**, or push to your database, BI tools and webhooks through the Apify API. Connect it to **Make, n8n or Zapier** to build automated real-estate pipelines.

### 🤖 AI Agents, MCP & RAG Integration

**VivaReal Scraper** works natively as an on-demand data tool for AI assistants and autonomous workflows.

Connect this Actor directly to **Apify AI**, **Claude Desktop**, **Cursor**, **VS Code**, **Windsurf**, **LangChain**, or **LlamaIndex** via the official **Apify MCP Server** — no custom wrapper code needed:

```json
{
  "mcpServers": {
    "apify": {
      "type": "http",
      "url": "https://mcp.apify.com?tools=logiover/vivareal-scraper"
    }
  }
}
```

- **Schema-typed inputs & outputs:** Clean JSON records with explicit `.actor/input_schema.json` and `.actor/output_schema.json` definitions so LLM agents infer parameters and parse fields accurately without HTML noise.
- **Bounded & predictable runs:** Built-in volume caps and pay-per-result budget guards prevent runaway agent tool loops.
- **RAG & automation ready:** Stream run datasets straight into vector stores, n8n, Make, Zapier, or webhook pipelines.

### 💬 Support, Issues & Reviews

- **Bug reports & target-site changes:** Hit an unexpected empty result or selector change? [Open a ticket in the Issues tab](https://apify.com/logiover/vivareal-scraper/issues) with your **Run ID** or sample input — we actively monitor issues and ship fixes fast.
- **Feature & field requests:** Need an additional data attribute or filter? [Request it in the Issues tab](https://apify.com/logiover/vivareal-scraper/issues).
- **Enjoying this Actor?** If it saved you engineering time, please consider leaving an honest [review on Apify Store](https://apify.com/logiover/vivareal-scraper/reviews) or bookmarking [logiover/vivareal-scraper](https://apify.com/logiover/vivareal-scraper) — organic developer feedback helps others discover reliable tools and keeps maintenance prioritized.

### ⚖️ Legal

This Actor extracts only publicly available data and is intended for legitimate research, analytics and lead-generation use. You are responsible for complying with VivaReal's terms of service, Brazil's LGPD and any applicable local laws.

***

This Actor is an independent tool. It is not affiliated with, endorsed by, or sponsored by VivaReal; VivaReal and all other trademarks mentioned here are the property of their respective owners.

### VivaReal scraping — frequently asked questions

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

No. This Actor reads publicly available pages and feeds, so there is nothing to register for and no credentials to manage.

#### How do I export VivaReal data to CSV, Excel, JSON or Google Sheets?

Open the **Storage** tab after a run and pick the format you want — CSV, Excel, JSON, XML or an HTML table. For Google Sheets, Airtable or a database, use the dataset URL or the Apify API so the sheet refreshes itself on every run.

#### Can I schedule this VivaReal scraper to run daily or hourly?

Yes. Use the **Schedules** tab and pick a cadence. Daily is enough for most tracking work; pick hourly only if the listings you care about really do change that fast.

#### How many listings can I get, and what does it cost?

See the volume section above for a measured figure. Billing is per result, so you pay for the rows you actually receive and a run that finds nothing costs nothing.

#### Is scraping VivaReal legal?

This Actor collects only information that VivaReal publishes publicly. It does not log in, does not defeat access controls and does not touch private data. You remain responsible for how you use the output, including under GDPR and similar rules where personal data is involved.

#### What happens if VivaReal blocks the run or changes its layout?

A refused exit IP is swapped for a fresh one within a quarter of a second and retried, and rate limiting is waited out rather than fought. If nothing gets through, the run **fails with the reason** instead of reporting success with zero rows — so an empty result always means "no matches", never "the source would not answer".

#### Can I use this with an AI agent, LangChain or an MCP client?

Yes. The Actor is callable over the Apify API and through Apify's MCP server, so an agent can run it and read the dataset back as a tool call.

### 📝 Changelog

#### 2026-11-11

- Added reliable terminal run status telemetry and structured Apify AI / MCP Server (`mcp.apify.com`) tool configuration.
- Added direct Issues & Reviews support links and refreshed live maintenance verification.

#### 2026-11-01

- Monthly health check (2026-11-01): a live run on the current build completed successfully and returned data. Input options, output fields and pricing are unchanged.
- README refreshed: 2 links to retired Actors removed; independence disclaimer added.

#### 2026-10-15

- Every request now has a hard time limit, so a proxy connection that stalls can no longer hold up the run or push it past its timeout.
- A run that reaches its maximum cost per run now stops cleanly with its results saved and a status message, instead of ending as aborted.
- A proxy group your account cannot use no longer stops the run at start-up; it falls back to the default Apify Proxy.
- Runs with a short timeout (API and AI-agent calls) now finish inside it with what they collected, instead of being cut off.
- Memory is managed within the run's own limit, which removes a rare out-of-memory crash on large pages.
- The prefilled example for `maxResults` is now 285 (was 100).
- The default used when the field is left out for `maxResults` is now 5,853 (was 1,000).

#### 2026-09-23

- Fleet-wide quality audit. Verified end to end against live data and re-checked the input schema, the output columns and the run configuration.
- Output verified on a live run: 32 columns returned, 90.4% of cells populated.
- Run reliability reviewed: 100.0% of public runs succeeded in the last 30 days.
- Input schema, output schema and pricing configuration reviewed.

#### 2026-09-01

- Fleet-wide health check. Verified against this Actor's real run history: 30-day success rate, output row counts, per-field fill rates, and peak memory against the configured memory limit.
- Reviewed for the failure patterns that have cost this fleet runs — unguarded proxy setup, retry loops that can outlast the run's own time budget, and full-page HTML parsing that can exhaust a small container.
- No change to input, output fields or scraping logic.

#### 2026-08-11

- Maintenance release: refreshed the build and dependencies.
- Re-verified live execution, non-empty structured output and dataset field/type integrity.
- Reviewed reliability (retries, pagination) and output quality as part of a full-fleet QA pass.

#### 2026-08-01

- Completed the August 2026 full health check: verified empty/programmatic default, Console UI default, and two source-informed alternative inputs on Apify.
- Confirmed successful live execution, non-empty structured output, dataset-field/type integrity, and logical sample quality within the 5-minute quality window.

#### 2026-07-06

- ✨ README overhaul: richer nested output sample with real field names, three ready-to-run example scenarios, cross-country real-estate suite links, badges and clearer quick-start.

#### 2026-07-01

- Maintenance pass: re-verified end-to-end on live data within the 5-minute quality window; sharpened Store SEO metadata and expanded the FAQ with high-intent long-tail questions.
- Added ready-to-run example tasks that cover common real-world use cases.

#### 2026-06-28

- Health check passed — Actor verified working end-to-end on the Apify platform; changelog refreshed for Store quality compliance.

#### 2026-06-20

- Maintenance & reliability pass: re-verified end-to-end against live data; refreshed the prefilled example input and tuned run defaults for faster, lower-cost runs.

#### 2026-06-07

- Docs: added coverage for VivaReal API alternative use, exporting VivaReal data to CSV/JSON, and scraping imóveis without an API or login.

***

\*Maintained: last verified 2026-11-11 — checked end-to-end against live run history (reliability, output fields and types, and time/memory budgets).

# Changelog

This Actor's version history is a separate document: https://apify.com/logiover/vivareal-scraper/changelog.md

# Actor input Schema

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

Paste one or more vivareal.com.br search/result page URLs (e.g. https://www.vivareal.com.br/venda/sp/sao-paulo/apartamento_residencial/). The actor derives the location, operation (sale/rent), property type and price filters from each URL. Leave empty to use the builder fields below.

## `operationType` (type: `string`):

Buy (SALE) or rent (RENTAL). Used in builder mode when no search URLs are given.

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

USED = resale/used properties. DEVELOPMENT = new launches.

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

Filter by property type (builder mode). Leave blank for all types.

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

City name in Portuguese, e.g. 'São Paulo', 'Rio de Janeiro', 'Curitiba' (builder mode).

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

Brazilian state (optional, improves city accuracy in builder mode). Leave 'Any' to let the city resolve on its own.

## `locationId` (type: `string`):

Optional VivaReal locationId to target a neighborhood precisely, e.g. 'BR>Sao Paulo>NULL>Sao Paulo>Zona Oeste>Pinheiros'. Overrides city/state when set.

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

Minimum price filter in Brazilian Reais.

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

Maximum price filter in Brazilian Reais.

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

Minimum number of bedrooms.

## `maxResults` (type: `integer`):

Maximum listings to collect across all searches. A single query returns up to ~1,476 listings; add more cities/filters or URLs to reach more.

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

VivaReal data is served from Brazil. Keep the default Apify Proxy · RESIDENTIAL group · country BR for reliable access.

## Actor input object example

```json
{
  "searchUrls": [
    "https://www.vivareal.com.br/venda/sp/sao-paulo/apartamento_residencial/"
  ],
  "operationType": "SALE",
  "listingType": "USED",
  "propertyType": "",
  "city": "São Paulo",
  "state": "São Paulo",
  "maxResults": 285,
  "proxyConfiguration": {
    "useApifyProxy": true,
    "apifyProxyGroups": [
      "RESIDENTIAL"
    ],
    "apifyProxyCountry": "BR"
  }
}
```

# Actor output Schema

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

All records extracted by this run. Open the Dataset tab to browse, filter, and export as CSV, JSON, or Excel.

# 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": [],
    "city": "São Paulo",
    "state": "São Paulo",
    "maxResults": 285,
    "proxyConfiguration": {
        "useApifyProxy": true,
        "apifyProxyGroups": [
            "RESIDENTIAL"
        ],
        "apifyProxyCountry": "BR"
    }
};

// Run the Actor and wait for it to finish
const run = await client.actor("logiover/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 = {
    "searchUrls": [],
    "city": "São Paulo",
    "state": "São Paulo",
    "maxResults": 285,
    "proxyConfiguration": {
        "useApifyProxy": True,
        "apifyProxyGroups": ["RESIDENTIAL"],
        "apifyProxyCountry": "BR",
    },
}

# Run the Actor and wait for it to finish
run = client.actor("logiover/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 '{
  "searchUrls": [],
  "city": "São Paulo",
  "state": "São Paulo",
  "maxResults": 285,
  "proxyConfiguration": {
    "useApifyProxy": true,
    "apifyProxyGroups": [
      "RESIDENTIAL"
    ],
    "apifyProxyCountry": "BR"
  }
}' |
apify call logiover/vivareal-scraper --silent --output-dataset

```

## MCP server setup

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