# QuintoAndar Scraper & New-Listing Monitor - Brazil Rent & Sale (`neverempty/quintoandar-listings-monitor`) Actor

For renters, buyers and Brazil real estate research: QuintoAndar listings as an API by city or neighbourhood. Rent (aluguel), condomínio, IPTU and total monthly cost in BRL as separate numbers, sale price, m², bedrooms, parking, coordinates. Monitoring returns only new listings and price drops.

- **URL**: https://apify.com/neverempty/quintoandar-listings-monitor.md
- **Developed by:** [NeverEmpty](https://apify.com/neverempty) (community)
- **Categories:** Real estate, Lead generation, Automation
- **Stats:** 2 total users, 1 monthly users, 100.0% runs succeeded, 0 bookmarks
- **User rating**: No ratings yet

## Pricing

from $4.50 / 1,000 listing returneds

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

## QuintoAndar Scraper & New-Listing Monitor - Brazil Rent & Sale

Pull Brazilian property listings from **QuintoAndar (quintoandar.com.br)** as clean JSON, **newest first**: monthly **rent, condomínio, IPTU and the total monthly cost as separate numbers in BRL**, the sale price, area in m², bedrooms, suites, bathrooms, parking spaces, furnished or not, street, neighbourhood, city and approximate map coordinates (rounded to about 100 m). Search **for rent (alugar) or for sale (comprar)** by **city** or by **neighbourhood (bairro)** - São Paulo, Rio de Janeiro, Belo Horizonte, Curitiba, Porto Alegre, Brasília and every other city QuintoAndar serves.

Turn on monitoring and every later run returns only **new listings and price drops** since the last run, with the previous price.

*Unofficial. This Actor is not affiliated with, endorsed by, or sponsored by QuintoAndar. All product names are trademarks of their respective owners.*

No API key, no login. It asks QuintoAndar's public search the same question its own website asks when a visitor scrolls a city, at a gentle pace, and checks robots.txt on every run.

***

### Who uses this

- **Renters and buyers** who want the newest flats in a neighbourhood the moment they appear, with the real monthly cost (rent + condomínio + IPTU) side by side.
- **Real estate agents and investors** tracking asking rents and sale prices per neighbourhood, and price drops.
- **Analysts and proptech teams** who need a daily feed of Brazilian listings in a spreadsheet, database or n8n / Make / Zapier flow.

### Monitoring: run it daily, get only what changed

1. Set your city (and neighbourhood if you like), switch **Monitoring mode** on, and schedule the Actor (daily is typical).
2. The **first run** remembers every listing and its price. It returns one free `monitoring-started` row and charges nothing.
3. Every **later run** returns only:
   - `changeType: "new"` - a listing that was not there last time;
   - `changeType: "price-drop"` - a listing whose rent (rent searches) or sale price (buy searches) went down, with `previousPriceBrl`.
4. If nothing changed you get one free `no-new-listings` row. Each page of 50 listings that was compared without returning a change is charged as one small `search-checked` event (see Pricing).

The memory is kept per search (rent/buy + place), so you can watch several cities or neighbourhoods from one account. `resetMonitoringState` starts a search over from a free baseline.

**Coverage:** QuintoAndar serves at most **1,000 listings per search, newest first**. New listings always land at the top, so they are always seen. Price drops are watched on those 1,000 newest listings; in a very large city (São Paulo has 40,000+ rentals) split the watch by neighbourhood to cover more. The run log and the first-run row say how many listings were compared.

### What makes the data usable

- **Costs as separate numbers.** `rentBrl`, `condominiumBrl`, `iptuBrl`, `condominiumPlusIptuBrl` and `totalMonthlyCostBrl` (QuintoAndar's total, which also includes its fees and fire insurance) - no parsing of "R$ 3.400" strings.
- **Nothing invented.** A value QuintoAndar gives as 0 or does not give is `null`, not 0. The rent of a listing that is only for sale, and the sale price of a listing that is only for rent, are `null` (QuintoAndar sometimes carries an estimate there that is not an asking price).
- **Only the place you asked for.** QuintoAndar mixes listings from nearby places into a search. By default only listings QuintoAndar itself tags as being in your city or neighbourhood are returned (`areaMatch`: `same-city` / `same-neighbourhood`). In a neighbourhood search QuintoAndar's own count includes the nearby ones too - e.g. 670 for Jardim Botânico (Rio) of which 180 are tagged to the neighbourhood or its box. Turn on `includeNearby` to also get the others (`areaMatch`: `inside-area-bounds` = inside the neighbourhood's rectangle, often the next bairro; `nearby` = elsewhere).
- **Unknown places are said out loud.** A misspelt city returns a free `no-such-location` row instead of somebody else's listings.
- **QuintoAndar's own tags** as booleans: `isNewAd`, `rentPriceDecreasedTag`, `salePriceDecreasedTag`.

Measured on 2026-10-09 (200 rentals in São Paulo and 200 sales in Rio de Janeiro): rent, area, bedrooms, bathrooms, parking, street, neighbourhood and coordinates filled on 99-100% of listings; condomínio on 82% (rent) / 90% (sale); IPTU on 66% / 76% (houses outside a condomínio often have neither).

### Input

| Field | What it does |
|---|---|
| `transaction` | `rent` (alugar) or `buy` (comprar). Empty = rent. |
| `city` | City name (`São Paulo`, `Rio de Janeiro`, accents optional) or QuintoAndar's code (`sao-paulo-sp-brasil`). |
| `state` | Two-letter state code (`SP`, `RJ`, `MG` ...). Needed with a city name. |
| `neighbourhood` | Optional bairro, e.g. `Vila Mariana`, `Copacabana`. |
| `searchUrl` | Optional: paste a QuintoAndar list address instead of the fields above. |
| `maxListings` | How many listings to return (1-1,000). Empty = 20. |
| `maxPages` | Cap on pages of 50 (max 20). |
| `minPrice` / `maxPrice` | BRL. Rent searches compare the monthly rent; buy searches the sale price. |
| `minAreaSqm` / `maxAreaSqm` / `minBedrooms` | Size filters. |
| `propertyTypes` | `Apartment`, `House`, `Casa de Condomínio`, `Studio` (English or Portuguese). |
| `furnishedOnly` | Drop listings marked not furnished. |
| `includeNearby` | Also return the nearby listings QuintoAndar suggests. |
| `monitoringMode` / `resetMonitoringState` | See above. |

Example - the newest 20 rentals in São Paulo:

```json
{ "transaction": "rent", "city": "São Paulo", "state": "SP", "maxListings": 20 }
```

Example - watch flats for sale in Copacabana under R$ 1,200,000:

```json
{ "transaction": "buy", "city": "Rio de Janeiro", "state": "RJ", "neighbourhood": "Copacabana", "maxPrice": 1200000, "propertyTypes": ["Apartment"], "monitoringMode": true }
```

### Output

One row per listing:

```json
{
  "status": "ok",
  "listingId": "895469980",
  "url": "https://www.quintoandar.com.br/imovel/895469980/alugar",
  "transaction": "rent",
  "propertyType": "House",
  "propertyTypeCode": "Casa",
  "rentBrl": 2400,
  "condominiumBrl": null,
  "iptuBrl": null,
  "condominiumPlusIptuBrl": null,
  "totalMonthlyCostBrl": 2502,
  "salePriceBrl": null,
  "areaSqm": 50,
  "bedrooms": 1,
  "suites": 0,
  "bathrooms": 1,
  "parkingSpaces": 1,
  "isFurnished": true,
  "street": "Rua Orlando Pellicci",
  "neighbourhood": "Cidade Líder",
  "city": "São Paulo",
  "latitude": -23.56,
  "longitude": -46.479,
  "isNewAd": true,
  "areaMatch": "same-city",
  "resolvedLocation": "São Paulo, SP",
  "siteTotalForSearch": 43512,
  "currency": "BRL"
}
```

Monitoring rows add `changeType` (`new` or `price-drop`) and, for drops, `previousPriceBrl`.

#### Rows that are never charged

| `status` | Meaning |
|---|---|
| `monitoring-started` | First monitoring run: the starting point was remembered. |
| `no-new-listings` | Monitoring: nothing new and nothing cheaper since the last run. |
| `no-filter-match` | Listings were read, but none passed your filters. |
| `no-results` | QuintoAndar answered with 0 listings for this search. |
| `no-such-location` | QuintoAndar does not know this place (check spelling and state). |
| `blocked` / `unreadable` | QuintoAndar did not answer normally. Nothing is guessed; try again later. |
| `disallowed-by-robots` | robots.txt disallows the address, so it was not requested. |

### Pricing

Pay per event: `listing-returned` for each listing row you receive, and in monitoring mode `search-checked` for each page of 50 listings compared without a change. Rows above are free. Set a maximum cost per run in Apify and the Actor stops cleanly at that limit; listings it could not hand over in monitoring mode come back on the next run.

### Notes

- Personal data: owner or agent names and phone numbers are not requested or returned. The street is given without a house number, as QuintoAndar shows it, and `latitude` / `longitude` are rounded to 3 decimals (about 100 m) so that a private home cannot be pinpointed.
- Classified ads that QuintoAndar shows from partner agencies are not included; the rows are the listings QuintoAndar manages itself (most of each city).
- Sorting is newest first. QuintoAndar's 1,000-per-search limit applies to every search.
- `siteTotalForSearch` is QuintoAndar's own count for the search, which includes the nearby listings it mixes in.

### Thanks for using this Actor

We build these tools for people who run them every day, and we improve them from what users tell us.

- **Missing a field, or need another filter?** Tell us in the **Issues** tab. If the data is there, we add it.
- **Found a bug or a wrong value?** Post the run ID in the **Issues** tab. Wrong data is the thing we fix first.

If this Actor saved you time, a short review helps other people find it.

# Actor input Schema

## `transaction` (type: `string`):

rent = listings for rent (alugar), buy = listings for sale (comprar). Ignored when a QuintoAndar search URL is given; empty = rent.

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

The city as people write it, e.g. São Paulo, Rio de Janeiro, Belo Horizonte, Curitiba (accents optional), or QuintoAndar's own location code such as sao-paulo-sp-brasil. Required unless a search URL is given.

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

Two-letter Brazilian state code of the city, e.g. SP, RJ, MG, PR, DF. Needed when the city is written as a name; not needed with a location code like sao-paulo-sp-brasil.

## `neighbourhood` (type: `string`):

Optional neighbourhood inside the city, e.g. Vila Mariana, Pinheiros, Copacabana. Empty = the whole city. Splitting a large city by neighbourhood also lets monitoring cover more listings (QuintoAndar serves at most 1,000 per search).

## `searchUrl` (type: `string`):

Optional: paste a QuintoAndar list address such as https://www.quintoandar.com.br/comprar/imovel/rio-de-janeiro-rj-brasil. When given, rent/buy, city, state and neighbourhood are taken from it and the fields above are ignored. Filters in the URL are not carried over; use the filters below.

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

How many listings to return, newest first. You are charged only for rows you receive. QuintoAndar serves at most 1,000 listings per search; empty = 20.

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

Hard cap on pages of 50 listings requested (at most 20). 0 or empty = decided from maxListings (monitoring: all 20 pages). Outside monitoring, reading pages is free and only returned listings are charged; in monitoring mode each page compared without a change is charged one search-checked event.

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

Keep listings at or above this price in reais: monthly rent for rent searches, sale price for buy searches. 0 or empty = no minimum. Listings without a price are kept.

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

Keep listings at or below this price in reais, e.g. 4000 for rent or 800000 for a purchase. 0 or empty = no maximum.

## `minAreaSqm` (type: `number`):

Keep listings with at least this usable area in square metres. 0 or empty = no minimum.

## `maxAreaSqm` (type: `number`):

Keep listings with at most this usable area in square metres. 0 or empty = no maximum.

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

Keep listings with at least this many bedrooms (quartos). 0 or empty = any.

## `propertyTypes` (type: `array`):

Keep only these property types: Apartment (Apartamento), House (Casa), House in a gated condominium (Casa de Condomínio), Studio / kitchenette (Kitnet, Studio). English or Portuguese names both work. Empty = all types.

## `furnishedOnly` (type: `boolean`):

On: drop listings QuintoAndar marks as not furnished. Off: keep all.

## `includeNearby` (type: `boolean`):

QuintoAndar mixes in listings from nearby places (the next neighbourhood or city). Off: return only listings QuintoAndar tags as being in the city or neighbourhood you searched. On: also return the others (areaMatch = inside-area-bounds or nearby).

## `monitoringMode` (type: `boolean`):

On: the first run remembers every listing and its price (free); every later run returns only listings that are new or cheaper since the last run, with changeType and previousPriceBrl. Off: return the current listings.

## `resetMonitoringState` (type: `boolean`):

On: forget what monitoring remembered for this search, so the next monitoring run starts again from a free baseline. Off: keep the memory.

## Actor input object example

```json
{
  "transaction": "rent",
  "city": "São Paulo",
  "state": "SP",
  "maxListings": 20,
  "furnishedOnly": false,
  "includeNearby": false,
  "monitoringMode": false,
  "resetMonitoringState": false
}
```

# Actor output Schema

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

One row per QuintoAndar listing, newest first: listing id and URL, rent or buy, property type, rent, condomínio, IPTU and total monthly cost in BRL as separate numbers, sale price in BRL, area in m², bedrooms, suites, bathrooms, parking spaces, furnished, street, neighbourhood, city, latitude and longitude, QuintoAndar's own tags (new ad, price decreased) and whether the listing is in the searched area. Monitoring rows add changeType (new or price-drop) and previousPriceBrl. Unknown places, searches with no results, filters that matched nothing and answers that could not be read come back as their own rows and are not charged.

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

// Run the Actor and wait for it to finish
const run = await client.actor("neverempty/quintoandar-listings-monitor").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 = {
    "transaction": "rent",
    "city": "São Paulo",
    "state": "SP",
    "maxListings": 20,
}

# Run the Actor and wait for it to finish
run = client.actor("neverempty/quintoandar-listings-monitor").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 '{
  "transaction": "rent",
  "city": "São Paulo",
  "state": "SP",
  "maxListings": 20
}' |
apify call neverempty/quintoandar-listings-monitor --silent --output-dataset

```

## MCP server setup

```json
{
    "mcpServers": {
        "apify": {
            "type": "http",
            "url": "https://mcp.apify.com/?tools=fetch-actor-details,neverempty/quintoandar-listings-monitor"
        }
    }
}
```

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/0BdtXJxLafehzuZre/builds/thUjv7dKJNvAD2kg8/openapi.json