# Imóveis BR Scraper (`gleaming_carp/imoveis-br-scraper`) Actor

- **URL**: https://apify.com/gleaming_carp/imoveis-br-scraper.md
- **Developed by:** [LatAm Data Tools](https://apify.com/gleaming_carp) (community)
- **Stats:** 2 total users, 1 monthly users, 100.0% runs succeeded, 0 bookmarks
- **User rating**: No ratings yet

## Pricing

from $2.00 / 1,000 listings

This Actor is paid per event. You are not charged for the Apify platform usage, but only a fixed price for specific events.

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

## Brazil Real Estate Scraper: ZAP, VivaReal, OLX & QuintoAndar

Scrape property listings **for sale or for rent** from Brazil's four largest real-estate portals — **ZAP Imóveis, VivaReal, OLX and QuintoAndar** — in a single run, with **one unified schema** and an optional **USD price at the official PTAX rate** (Banco Central do Brasil).

### What can this Brazil real estate scraper do?

- **Search by city and state** (e.g. São Paulo / SP, Rio de Janeiro / RJ, Belo Horizonte / MG) across all four portals at once, or choose only the portals you need.
- **Paste search URLs** copied from ZAP, VivaReal, OLX or QuintoAndar with any filters applied (price, bedrooms, neighborhood, property type...).
- **Unified fields across portals**: price, price per m², area, bedrooms, bathrooms, parking spots, condo fee, IPTU, neighborhood, city, state, amenities, image and URL.
- **USD conversion** at the official BCB PTAX sell rate, with rate, source and timestamp in every row.
- **Portal extras**: QuintoAndar adds total monthly rent cost, condo + IPTU, furnished and pets flags and estimated rental yield; OLX adds condo fee, IPTU, listing date and the professional/private flag.

Typical uses: price per m² analysis by neighborhood, investment and rental-yield research, market monitoring for agencies and developers, comparable listings (comps), and data for dashboards or AI agents.

### Input

| Field | Description | Default |
|---|---|---|
| `city`, `state` | City name and two-letter UF (used when no `startUrls` are given) | `São Paulo`, `SP` |
| `business` | `sale` (venda) or `rent` (aluguel) | `sale` |
| `portals` | Any of `zap`, `vivareal`, `olx`, `quintoandar` | all four |
| `startUrls` | Optional search URLs from the portals (filters kept; city search is skipped) | – |
| `maxItemsPerPortal` | Listings per portal / URL | `10` |
| `maxItems` | Hard cap for the whole run (also caps your cost) | `40` |
| `convertToUsd` | Add `price_usd` at PTAX | `true` |

Example input:

```json
{ "city": "Rio de Janeiro", "state": "RJ", "business": "rent", "portals": ["zap", "vivareal", "quintoandar"], "maxItemsPerPortal": 100, "maxItems": 300 }
```

### Output

One dataset item per listing. Download as JSON, CSV, Excel or HTML, or read it through the Apify API. Example:

```json
{
  "portal": "vivareal", "id": "2801202718",
  "url": "https://www.vivareal.com.br/imovel/casa-5-quartos-jardim-paulista-zona-sul-sao-paulo-com-garagem-550m2-venda-RS10900000-id-2801202718/",
  "title": "Casa para comprar com 550 m², 5 quartos, 5 banheiros, 4 vagas em Jardim Paulista, São Paulo",
  "business": "sale", "property_type": "House", "is_new_development": false,
  "price": 10900000, "currency": "BRL", "condo_fee": null, "iptu": null,
  "area_m2": 550, "price_per_m2": 19818, "bedrooms": 5, "bathrooms": 5, "parking_spots": 4,
  "street": "Rua Colatino Marques", "neighborhood": "Jardim Paulista", "city": "São Paulo", "state": "SP",
  "amenities": ["Elevator", "Pool", "Barbecue Grill", "Home Office"],
  "price_usd": 1981566,
  "usd_rate": { "brl_per_usd": 5.5007, "type": "ptax_sell", "source": "CambioKit / Banco Central do Brasil PTAX" },
  "page": 1, "search_url": "https://www.vivareal.com.br/venda/sp/sao-paulo/", "scraped_at": "2026-10-26T19:25:01.826Z"
}
```

### How much does it cost?

**Pay per result: US$0.002 per listing (US$2 per 1,000 listings).** No start fee, and you only pay for listings returned. The default run (up to 40 listings) costs at most US$0.08. Use `maxItems` or the maximum cost per run setting to control your spend.

### Personal data

This Actor collects **only property data**. It does **not** collect agent or owner names, phone numbers, emails or free-text descriptions. Use the data in accordance with each portal's terms and the laws that apply to you (including LGPD).

### Tips and limits

- **OLX** search by city/state is state-wide (OLX has no simple city URL): filter by `city` in the output, or pass an OLX city search URL in `startUrls`.
- **QuintoAndar** returns the first results page (~24 listings) per search.
- `neighborhood` is not always published by ZAP/VivaReal; `condo_fee`/`iptu` come from OLX (QuintoAndar gives `condo_plus_iptu`).
- Uses Brazilian residential proxies by default for reliable access.
- Works with Apify's MCP server (`mcp.apify.com`) so AI agents can call it as a tool.

### Disclaimer

This Actor is an independent tool and is not affiliated with, endorsed by or sponsored by ZAP Imóveis, VivaReal, OLX or QuintoAndar. All product and company names are trademarks of their respective owners and are used only to describe which public websites the Actor reads.

# Actor input Schema

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

City name, e.g. 'São Paulo', 'Rio de Janeiro', 'Belo Horizonte'. Used only when no listing URLs are given.

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

Two-letter state code (UF), e.g. SP, RJ, MG. Used only when no listing URLs are given.

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

Listings for sale or for rent.

## `portals` (type: `array`):

Which portals to search.

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

Search result URLs from ZAP, VivaReal, OLX or QuintoAndar with your filters applied. When given, the city/state search is skipped.

## `maxItemsPerPortal` (type: `integer`):

Stop each portal/URL after this many listings. QuintoAndar returns at most ~24 per search.

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

Hard cap for the whole run. Each listing is one charged event, so this also caps your cost (1,000 listings = US$2).

## `convertToUsd` (type: `boolean`):

Adds price_usd using the Banco Central do Brasil PTAX rate.

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

Brazilian residential proxies are used by default.

## Actor input object example

```json
{
  "city": "São Paulo",
  "state": "SP",
  "business": "sale",
  "portals": [
    "zap",
    "vivareal",
    "olx",
    "quintoandar"
  ],
  "maxItemsPerPortal": 10,
  "maxItems": 40,
  "convertToUsd": true
}
```

# Actor output Schema

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

Listings stored in the default dataset (one item per listing).

# 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 = {
    "city": "São Paulo",
    "state": "SP"
};

// Run the Actor and wait for it to finish
const run = await client.actor("gleaming_carp/imoveis-br-scraper").call(input);

// Fetch and print Actor results from the run's dataset (if any)
console.log('Results from dataset');
console.log(`💾 Check your data here: https://console.apify.com/storage/datasets/${run.defaultDatasetId}`);
const { items } = await client.dataset(run.defaultDatasetId).listItems();
items.forEach((item) => {
    console.dir(item);
});

// 📚 Want to learn more 📖? Go to → https://docs.apify.com/api/client/js/docs

```

## Python example

```python
from apify_client import ApifyClient

# Initialize the ApifyClient with your Apify API token
# Replace '<YOUR_API_TOKEN>' with your token.
client = ApifyClient("<YOUR_API_TOKEN>")

# Prepare the Actor input
run_input = {
    "city": "São Paulo",
    "state": "SP",
}

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

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

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

```

## CLI example

```bash
echo '{
  "city": "São Paulo",
  "state": "SP"
}' |
apify call gleaming_carp/imoveis-br-scraper --silent --output-dataset

```

## MCP server setup

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

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

## OpenAPI specification

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