# QuintoAndar Scraper (`ribtools/quintoandar-scraper`) Actor

QuintoAndar API for rentals (aluguel) and homes for sale (imóveis à venda): search by neighbourhood with filters or paste any QuintoAndar URL. Rent, total cost, sale price, price per m², condo fee, IPTU, area, rooms, photos and a market summary. Proxies included.

- **URL**: https://apify.com/ribtools/quintoandar-scraper.md
- **Developed by:** [RibTools](https://apify.com/ribtools) (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 $1.99 / 1,000 property data 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

## QuintoAndar Scraper

🇺🇸 [English](#what-is-quintoandar-scraper) | 🇧🇷 [Português](#quintoandar-scraper-pt-br)

Scrape **QuintoAndar** (quintoandar.com.br), Brazil's largest rental platform and a big home-sale portal: rentals (aluguel) and homes for sale (imóveis à venda) with rent, total monthly cost, sale price, **price per m²**, condo fee, IPTU, area, rooms, location and photos. Type a neighbourhood and a few filters, or paste any QuintoAndar URL. Every run ends with a free **market summary** of what it returned.

**O que faz?** Extrai imóveis para alugar e à venda do QuintoAndar: aluguel, valor total, preço de venda, preço por m², condomínio, IPTU, área, quartos, endereço e fotos. Digite um bairro e filtros, ou cole qualquer link do QuintoAndar. Cada execução termina com um resumo de mercado grátis. [Leia em português](#quintoandar-scraper-pt-br).

### What is QuintoAndar Scraper?

**QuintoAndar Scraper** collects home listings from [QuintoAndar](https://www.quintoandar.com.br/): the homes QuintoAndar rents and sells itself, agency classifieds ("Direto com a imobiliária") and new developments (lançamentos). It works like the site's own search box: type `Pinheiros, São Paulo`, choose rent or sale and a few filters, and get one structured item per home, ready for a price comparison, a market report or your own database.

Built for real-estate agents, consultants, investors and analysts, and for AI agents: it runs from ChatGPT, Claude or n8n through Apify's MCP server and integrations, and its input is plain fields an agent fills on the first try.

### What can this Actor do?

- **Search by typing** — a neighbourhood, street or city as you'd type it in QuintoAndar's search box, checked against the site so a place it doesn't know is skipped and named, never silently widened to a whole city
- **Filter like the site** — rent or buy, property type, bedrooms, bathrooms, parking, suites, price, area, furnished, pets, near the subway
- **Paste any QuintoAndar URL** — searches with any filters, single ads, classifieds, developments, condominiums
- **Price per m² on every home** — rent per m² for rentals, price per m² for homes to buy
- **Exact or nearby** — QuintoAndar pads small searches with nearby neighbourhoods; every home says `exact` or `nearby`, and one switch keeps only exact matches
- **Free market summary** — per search: median price, median price per m² with its 25th and 75th percentile, median area and total monthly cost, in the status message and the OUTPUT record
- **Past QuintoAndar's 1,000-result limit** — a bigger search runs as exact-location price bands; a capped one is a sample spread over every price band
- **Details add-on** — description, publication dates, CEP, floor range, all photos, yes/no feature lists
- **Premium proxies included** — Brazilian residential proxies built in at no extra cost

### What data can QuintoAndar Scraper extract?

| Field | Description | Example |
| ----- | ----------- | ------- |
| **Title** | The ad's heading | Apartamento para alugar com 86m², 2 quartos e 1 vaga |
| **Listing source** | `quintoandar`, `classified` or `development` | quintoandar |
| **Transaction** | `rent` or `sale` | rent |
| **Price** | Monthly rent, or sale price (R$) | 4300 |
| **Price per m²** | Price / area | 50.0 |
| **Total monthly cost** | Rent + condo fee + IPTU + fees | 5360 |
| **Condo fee / IPTU** | Monthly, R$ | 758 / 136 |
| **Rental yield** | Homes for sale: estimated monthly rent / price | 0.0041 |
| **Area, bedrooms, bathrooms, suites, parking** | Unit size and rooms | 86 m², 2, 2, 0, 1 |
| **Furnished, features, building features** | Unit and condominium features | AR_CONDICIONADO, PISCINA |
| **Address** | Street, neighbourhood, city, state, coordinates | Rua Capote Valente, Pinheiros, São Paulo, SP |
| **Location match** | `exact` (in the searched neighbourhood or city) or `nearby` (the site's "Outra localização") | exact |
| **Badges** | NEW_AD, RENT_PRICE_DECREASED, SALE_GOOD_PRICE… | RENT_ON_TERMINATION |
| **Photos** | Photo URLs and cover | https://www.quintoandar.com.br/img/xlg/… |
| **Development fields** | Name, price range, delivery month, construction status | Naeem, 2029-04, PRE_CONSTRUCTION |
| **Details (add-on)** | Description, dates, CEP, floors, all photos, features | see the output example |

### How to scrape QuintoAndar

#### Step-by-step tutorial:

1. **Add a location** — e.g. `Pinheiros, São Paulo` (always with the city), or paste QuintoAndar URLs
2. **Configure options** (optional) — rent or buy, filters, **Max results per search**, the details add-on
3. **Run the scraper** — Click "Start"; the status message reads back what it searches
4. **Download results** — Export data in JSON, CSV, or Excel format; the market summary is in the OUTPUT record

Proxies are included automatically — no setup required.

#### Compatible URL examples:

- **Rent search, any filters**: `https://www.quintoandar.com.br/alugar/imovel/pinheiros-sao-paulo-sp-brasil/de-2000-a-8000-aluguel/apartamento/2-quartos`
- **Sale search**: `https://www.quintoandar.com.br/comprar/imovel/pinheiros-sao-paulo-sp-brasil/apartamento`
- **City, zone or street**: `https://www.quintoandar.com.br/alugar/imovel/zona-oeste-sao-paulo-sp-brasil`
- **Price topics and recency**: `https://www.quintoandar.com.br/alugar/imovel/sao-paulo-sp-brasil/q-ate-2000`, `…/7-dias`
- **New developments**: `https://www.quintoandar.com.br/comprar/imovel/pinheiros-sao-paulo-sp-brasil/lancamento` (also `na-planta`, `em-construcao`, `pronto`)
- **Ad**: `https://www.quintoandar.com.br/imovel/895437977/alugar`
- **Classified ad**: `https://www.quintoandar.com.br/classificado/152274238/alugar`
- **Development**: `https://www.quintoandar.com.br/empreendimento/895686297`
- **Condominium**: `https://www.quintoandar.com.br/condominio/vn-capote-valente-pinheiros-sao-paulo-xplgs3jr8k` (the 20 rentals and 20 homes for sale its page shows)

**Important**: Only URLs matching these patterns will work.

### How much does it cost to scrape QuintoAndar?

QuintoAndar Scraper uses **pay-per-result (PPR)** pricing — you only pay for successfully extracted homes.

#### Is scraping QuintoAndar free?

The scraper follows Apify's PPR model with the following structure:

- **Base extraction**: one event per home returned, with every field above; the market summary is free
- **Details add-on**: one more event per home that got details

Pricing is optimized for efficiency, using minimal compute units while maintaining high success rates. Contact support for volume discounts on large-scale projects.

### Input configuration

The scraper accepts the following inputs:

#### Search locations

A neighbourhood, street or city as typed in QuintoAndar's search box, always with its city: `Pinheiros, São Paulo`, `Copacabana, Rio de Janeiro`, `Rua Teodoro Sampaio, Pinheiros, São Paulo`, `Campinas`. Outside the ~100 cities QuintoAndar serves, add the state: `Boa Viagem, Recife - PE`. One per line, each its own search. A place the site doesn't know is skipped and named in the status message.

#### QuintoAndar URLs

Any QuintoAndar search, ad, classified, development or condominium URL (see above). A URL keeps the filters it carries; the Filters section doesn't apply to it.

#### Max results per search

The most homes for each location and each URL (default 10). Each home is a charged event. Up to 1,000 you get the newest homes (QuintoAndar's own homes first, then agency classifieds, as the site orders them). QuintoAndar lists at most 1,000 homes per search; above 1,000 the scraper splits a bigger search into price bands of exact-location matches, newest first within each band. A cap below the search's total then takes a sample spread over every price band in proportion, so the market summary describes the whole market, not its cheapest homes. Homes with no price ("price on request") fall outside every band.

#### Rent or buy

`rent` (aluguel, the default) or `sale` (comprar).

#### Property types

Any of `apartment`, `house`, `house_condo` (casa de condomínio), `studio` (kitnet/studio); empty means all.

#### Bedrooms from

At least this many bedrooms (the site's highest choice is 4 or more).

#### Bathrooms from

At least this many bathrooms (up to 4).

#### Parking spaces from

At least this many parking spaces (up to 3).

#### Suites from

At least this many suites (up to 4).

#### Price from (R$)

Lowest monthly rent for rentals, lowest sale price for homes to buy.

#### Price to (R$)

Highest monthly rent for rentals, highest sale price for homes to buy.

#### Area from (m²)

Smallest usable area.

#### Area to (m²)

Largest usable area.

#### Furnished

`yes`, `no` or `any`.

#### Accepts pets

`yes`, `no` or `any` (rentals only).

#### Near the subway

`yes`, `no` or `any`.

#### Exact location only

Off (default): what the site shows, nearby neighbourhoods included (`location_match: nearby`). On: only homes in the place itself.

#### Fetch ad details (add-on)

Adds `details` to each home: description, publication dates (`listed_at`, `first_listed_at`), CEP, floor range, every photo and the count, pets and subway flags, condominium type, features present and absent, and for developments the developer and unit count. Charged only for homes that got details.

### Output example

```json
{
  "type": "property",
  "id": "892841647",
  "url": "https://www.quintoandar.com.br/imovel/892841647/alugar",
  "title": "Apartamento para alugar com 86m², 2 quartos e 1 vaga",
  "listing_source": "quintoandar",
  "property_type": "Apartamento",
  "transaction": "rent",
  "price": 4300,
  "currency": "BRL",
  "price_per_m2": 50.0,
  "rent_total_price": 5360,
  "condo_fee": 758,
  "iptu": 136,
  "rental_yield": null,
  "area_m2": 86.0,
  "bedrooms": 2,
  "bathrooms": 2,
  "suites": 0,
  "parking_spaces": 1,
  "is_furnished": true,
  "features": ["MAQUINA_DE_LAVAR", "MICROONDAS", "AREA_DE_SERVICO"],
  "complex_features": ["PERTO_DE_METRO_OU_TREM"],
  "condo_name": "Condomínio Edifício Lucilla",
  "region": "SP",
  "city": "São Paulo",
  "neighborhood": "Pinheiros",
  "street": "Rua Capote Valente",
  "latitude": -23.5512631,
  "longitude": -46.6801692,
  "location_match": "exact",
  "seller_type": null,
  "is_exclusive": false,
  "badges": ["RENT_ON_TERMINATION"],
  "photos": ["https://www.quintoandar.com.br/img/xlg/892841647-926.5125016135452IMG6937.jpg"],
  "thumbnail": "https://www.quintoandar.com.br/img/xlg/892841647-926.5125016135452IMG6937.jpg",
  "price_is_starting_from": false,
  "development_id": null,
  "development_name": null,
  "development_price_max": null,
  "development_area_max_m2": null,
  "development_bedrooms_max": null,
  "construction_status": null,
  "development_delivery": null,
  "search": "Pinheiros, São Paulo",
  "details": {
    "description": "Localizado no coração do bairro de Pinheiros, a duas quadras do metrô Sumaré…",
    "listed_at": "2026-10-22T22:04:32Z",
    "first_listed_at": "2023-09-29T22:06:11Z",
    "region": "SP",
    "zip_code": "05409-000",
    "floor_min": 8,
    "floor_max": 11,
    "photos": ["https://www.quintoandar.com.br/img/xlg/892841647-926.5125016135452IMG6937.jpg"],
    "photo_count": 36,
    "accepts_pets": true,
    "near_subway": true,
    "condo_type": "Normal",
    "features": ["Box", "Armários no quarto"],
    "features_absent": ["Varanda", "Piscina privativa"],
    "developer_name": null,
    "development_units": null
  }
}
```

The OUTPUT record (Storage → Key-value store, or the run's "Searches and market summary" output) holds, per search, what ran or was skipped and why, the homes listed and returned, and the market summary:

```json
{
  "search": "Pinheiros, São Paulo",
  "kind": "location",
  "resolved": "Pinheiros, São Paulo - SP, Brasil",
  "url": "https://www.quintoandar.com.br/alugar/imovel/pinheiros-sao-paulo-sp-brasil",
  "listed_total": 6460,
  "returned": 10,
  "reason": null,
  "summary": {"rent": {"all": {"count": 10, "price_median": 4400, "price_per_m2_median": 89.59, "price_per_m2_p25": 46.11, "price_per_m2_p75": 109.72, "area_median": 46.0, "rent_total_median": 5374}}}
}
```

You can download the dataset extracted by **QuintoAndar Scraper** in various formats such as **JSON, HTML, CSV, or Excel**. The data is automatically cleaned and normalized for immediate use in analysis tools, databases, or business applications.

### Use cases and applications

- **Comparables for a price evaluation** — the homes around a property, with price per m² and exact or nearby match
- **Rental market reports** — median rent and rent per m² by neighbourhood, furnished or not, near the subway or not
- **Investment screening** — sale price per m² and the site's rental yield estimate
- **New developments tracking** — launches, price ranges and delivery dates by neighbourhood

### Use with ChatGPT, Claude or n8n

Connect Apify's MCP server (mcp.apify.com) to ChatGPT or Claude, or use the Apify node in n8n, and ask in plain words. The agent fills the typed fields; the run's final status message carries the market summary, so the answer comes back with it.

- *"Use the QuintoAndar Scraper to find 2-bedroom apartments for rent in Pinheiros, São Paulo, up to R$ 6,000, and tell me the median rent per m², exact matches only."*
- *"With the QuintoAndar Scraper, get 50 apartments for sale in Moema, São Paulo between 60 and 90 m² and compare their price per m² with Vila Mariana."*

### Integrations and API access

QuintoAndar Scraper seamlessly integrates with popular platforms:

- **Zapier** — Automate data workflows and notifications (via [Apify Zapier integration](https://docs.apify.com/platform/integrations/zapier))
- **Make (Integromat)** — Create complex automation scenarios (via [Apify Make integration](https://www.make.com/en/integrations/apify))
- **Google Sheets** — Direct data export for analysis
- **REST API** — Programmatic access to extracted data ([instructions here](https://docs.apify.com/academy/api/run-actor-and-retrieve-data-via-api))
- **Python/Node.js SDKs** — Easy integration into applications ([instructions here](https://docs.apify.com/academy/api/run-actor-and-retrieve-data-via-api#javascript-and-python-client))

### FAQ and Support

#### Do I need to configure a proxy?

No. The Actor includes Brazilian residential proxies automatically at no additional cost. There's nothing to configure.

#### Why do some homes say "nearby"?

QuintoAndar pads a search with homes from neighbouring areas ("Outra localização") and counts them in its total. The scraper returns what the site shows and marks those homes `location_match: nearby`; turn on **Exact location only** to drop them. Each home is matched against the place searched, as the site matches it: its neighbourhood, or its city on a city search. On a city search the site's exact matches take in the metropolitan area, so with **Exact location only** those homes count as exact. Searches by zone or street without filters, pasted ads and condominium pages leave the field empty.

#### Why was my location skipped?

A place QuintoAndar doesn't know makes the site search a whole city or a random point. The scraper checks every typed location against the site first and skips it with a reason in the status message instead of charging you for the wrong homes. Add the city (`Centro, São Paulo`), or the state for a city outside QuintoAndar's list (`Boa Viagem, Recife - PE`).

#### How often is the data updated?

QuintoAndar updates listings in real-time. For fresh data, schedule regular scraper runs or use our API for on-demand extraction.

#### What if some URLs don't work?

The scraper only supports specific URL patterns from QuintoAndar. Ensure your URLs match the compatible formats listed above. URLs outside these patterns are skipped and named in the status message.

#### Do you offer custom solutions?

Absolutely! We can customize the scraper for specific requirements, additional data points, or integration with your existing systems. Contact us through the Issues tab for enterprise solutions.

#### Need help or have feedback?

- **Report issues**: Use the Issues tab for bug reports and feature requests
- **Custom development**: Contact us for tailored solutions and enterprise integrations

***

### QuintoAndar Scraper (PT-BR)

🇺🇸 [English](#what-is-quintoandar-scraper) | 🇧🇷 [Português](#quintoandar-scraper-pt-br)

O **QuintoAndar Scraper** coleta imóveis do [QuintoAndar](https://www.quintoandar.com.br/), a maior plataforma de aluguel do Brasil e um grande portal de venda: os imóveis que o próprio QuintoAndar aluga e vende, os classificados de imobiliárias ("Direto com a imobiliária") e os lançamentos. Funciona como a busca do site: digite `Pinheiros, São Paulo`, escolha alugar ou comprar e alguns filtros, e receba um item estruturado por imóvel, pronto para uma avaliação de preço, um relatório de mercado ou o seu banco de dados.

Feito para corretores, consultores, investidores e analistas, e para agentes de IA: roda pelo ChatGPT, Claude ou n8n através do servidor MCP e das integrações da Apify, com campos simples que um agente preenche de primeira.

#### O que o Actor faz

- **Busca digitada** — bairro, rua ou cidade como na caixa de busca do QuintoAndar, conferidos no site: um lugar que o site não conhece é pulado e informado, nunca ampliado para a cidade inteira
- **Filtros do site** — alugar ou comprar, tipo de imóvel, quartos, banheiros, vagas, suítes, preço, área, mobiliado, aceita pets, perto do metrô
- **Qualquer link do QuintoAndar** — buscas com filtros, anúncios, classificados, lançamentos, condomínios
- **Preço por m² em todo imóvel** — aluguel por m² na locação, preço por m² na venda
- **Exato ou próximo** — o QuintoAndar completa buscas pequenas com bairros vizinhos; cada imóvel diz `exact` ou `nearby`, e uma opção mantém só os exatos
- **Resumo de mercado grátis** — por busca: preço mediano, preço por m² mediano com percentis 25 e 75, área mediana e custo total mensal, na mensagem de status e no registro OUTPUT
- **Além do limite de 1.000 resultados** — uma busca maior roda em faixas de preço só com o local exato; com um máximo menor, uma amostra de todas as faixas
- **Add-on de detalhes** — descrição, datas de publicação, CEP, andares, todas as fotos, comodidades com sim/não
- **Proxies incluídos** — proxies residenciais brasileiros sem custo extra

#### Como usar

1. **Adicione um local** — ex.: `Pinheiros, São Paulo` (sempre com a cidade), ou cole links do QuintoAndar
2. **Configure** (opcional) — alugar ou comprar, filtros, **Max results per search**, o add-on de detalhes
3. **Execute** — clique em "Start"; a mensagem de status confirma o que está sendo buscado
4. **Baixe os resultados** — JSON, CSV ou Excel; o resumo de mercado fica no registro OUTPUT

#### Campos de entrada

- **Search locations (locais)** — bairro, rua ou cidade, sempre com a cidade: `Pinheiros, São Paulo`, `Copacabana, Rio de Janeiro`, `Campinas`. Fora das cidades atendidas pelo QuintoAndar, informe o estado: `Boa Viagem, Recife - PE`. Um por linha.
- **QuintoAndar URLs (links)** — qualquer link de busca, anúncio, classificado, lançamento ou condomínio; o link mantém os próprios filtros.
- **Max results per search (máximo por busca)** — quantos imóveis por local e por link (padrão 10). Cada imóvel é um evento cobrado. Até 1.000, os mais recentes (os imóveis do próprio QuintoAndar primeiro, depois os classificados, na ordem do site). O QuintoAndar mostra no máximo 1.000 por busca; acima disso o scraper divide a busca em faixas de preço só com o local exato, dos mais recentes em cada faixa. Um máximo menor que o total da busca pega uma amostra proporcional de todas as faixas, então o resumo descreve o mercado inteiro, não só os mais baratos. Imóveis sem preço ("sob consulta") ficam fora das faixas.
- **Rent or buy (alugar ou comprar)** — `rent` (aluguel, padrão) ou `sale` (comprar).
- **Property types (tipos)** — `apartment` (apartamento), `house` (casa), `house_condo` (casa de condomínio), `studio` (kitnet/studio); vazio = todos.
- **Bedrooms / Bathrooms / Parking spaces / Suites from** — mínimo de quartos (até 4+), banheiros (até 4+), vagas (até 3+) e suítes (até 4+).
- **Price from / to (R$)** — aluguel mensal na locação, preço de venda na compra.
- **Area from / to (m²)** — área útil.
- **Furnished / Accepts pets / Near the subway** — mobiliado, aceita pets (só aluguel), perto do metrô: `yes`, `no` ou `any`.
- **Exact location only (só o local exato)** — desligado (padrão): o que o site mostra, com bairros vizinhos (`location_match: nearby`). Ligado: só imóveis no próprio local.
- **Fetch ad details (add-on de detalhes)** — descrição, datas, CEP, andares, todas as fotos, comodidades presentes e ausentes; nos lançamentos, a incorporadora. Cobrado só nos imóveis que receberam detalhes.

#### Quanto custa

Cobrança por resultado (pay-per-result): um evento por imóvel retornado; o resumo de mercado é grátis. O add-on de detalhes é um evento a mais por imóvel que recebeu detalhes. Proxies incluídos.

#### Use com ChatGPT, Claude ou n8n

Conecte o servidor MCP da Apify (mcp.apify.com) ao ChatGPT ou ao Claude, ou use o nó da Apify no n8n, e peça em português. O agente preenche os campos; a mensagem de status final traz o resumo de mercado.

- *"Use o QuintoAndar Scraper para buscar apartamentos de 2 quartos para alugar em Pinheiros, São Paulo, até R$ 6.000, e me diga o aluguel mediano por m², só no local exato."*
- *"Com o QuintoAndar Scraper, pegue 50 apartamentos à venda em Moema, São Paulo, entre 60 e 90 m², e compare o preço por m² com a Vila Mariana."*

#### Perguntas frequentes

**Preciso configurar proxy?** Não. Proxies residenciais brasileiros já vêm incluídos.

**Por que alguns imóveis dizem "nearby"?** O QuintoAndar completa a busca com imóveis de áreas vizinhas ("Outra localização") e conta esses imóveis no total. O scraper devolve o que o site mostra e marca esses imóveis como `nearby`; ligue **Exact location only** para tirá-los. Cada imóvel é comparado com o local buscado, como o site compara: o bairro, ou a cidade numa busca por cidade. Numa busca por cidade, o resultado exato do site inclui a região metropolitana; com **Exact location only** esses imóveis contam como exatos. Buscas por zona ou rua sem filtros, anúncios colados e páginas de condomínio deixam o campo vazio.

**Por que meu local foi pulado?** Um lugar que o QuintoAndar não conhece faz o site buscar a cidade inteira ou um ponto qualquer. O scraper confere cada local antes e pula com o motivo na mensagem de status, em vez de cobrar por imóveis errados. Inclua a cidade (`Centro, São Paulo`) ou, fora das cidades do QuintoAndar, o estado (`Boa Viagem, Recife - PE`).

**Dúvidas ou sugestões?** Use a aba Issues.

# Changelog

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

# Actor input Schema

## `locations` (type: `array`):

A neighbourhood, street or city as typed in QuintoAndar's search box, always with its city: `Pinheiros, São Paulo`, `Copacabana, Rio de Janeiro`, `Rua Teodoro Sampaio, Pinheiros, São Paulo`, `Campinas`. Outside QuintoAndar's cities add the state: `Boa Viagem, Recife - PE`. One per line, each its own search. A place the site doesn't know is skipped and named, never widened.

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

Pages copied from the browser: a search (`https://www.quintoandar.com.br/alugar/imovel/pinheiros-sao-paulo-sp-brasil/apartamento`, any filters, `/comprar/...` for sale, `/lancamento` for new developments), an ad (`/imovel/...`, `/classificado/...`), a development (`/empreendimento/...`) or a condominium (`/condominio/...`). A URL keeps its own filters; the Filters section doesn't apply to it.

## `maxRequests` (type: `integer`):

Maximum number of homes for each location and each URL above (default 10); each home is a charged event. Up to 1,000: the newest. Above 1,000 a big search runs as exact-location price bands (QuintoAndar lists at most 1,000 per search); a cap below its total takes a sample spread over every price band.

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

Homes for rent (aluguel) or for sale (à venda).

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

Only these types; empty means all: `apartment`, `house`, `house_condo` (casa de condomínio), `studio` (kitnet/studio).

## `bedroomsFrom` (type: `integer`):

At least this many bedrooms (quartos). QuintoAndar's highest choice is 4 (4 or more).

## `bathroomsFrom` (type: `integer`):

At least this many bathrooms. Highest choice 4.

## `parkingFrom` (type: `integer`):

At least this many parking spaces (vagas). Highest choice 3.

## `suitesFrom` (type: `integer`):

At least this many suites (suítes). Highest choice 4.

## `priceFrom` (type: `integer`):

Lowest price in reais: the monthly rent (aluguel) for rentals, the sale price for homes to buy.

## `priceTo` (type: `integer`):

Highest price in reais: the monthly rent for rentals, the sale price for homes to buy.

## `areaFrom` (type: `integer`):

Smallest usable area in square meters.

## `areaTo` (type: `integer`):

Largest usable area in square meters.

## `furnished` (type: `string`):

Furnished (mobiliado) homes only, unfurnished only, or either.

## `acceptsPets` (type: `string`):

Rentals that accept pets, that don't, or either. Rentals only.

## `nearSubway` (type: `string`):

Homes near a subway or train station (próximo ao metrô), not near one, or either.

## `exactLocationOnly` (type: `boolean`):

QuintoAndar pads small searches with homes in nearby neighbourhoods (`location_match: nearby`). On: only homes in the place itself. Off (default): what the site shows.

## `detailsAddon` (type: `boolean`):

Description, publication dates, CEP, floor range, every photo, feature lists (yes and no), pets and subway flags; developer for new developments. One extra page per home; charged only for homes that got details.

## Actor input object example

```json
{
  "locations": [
    "Pinheiros, São Paulo"
  ],
  "startUrls": [
    "https://www.quintoandar.com.br/alugar/imovel/pinheiros-sao-paulo-sp-brasil/apartamento"
  ],
  "maxRequests": 10,
  "transaction": "rent",
  "furnished": "any",
  "acceptsPets": "any",
  "nearSubway": "any",
  "exactLocationOnly": false,
  "detailsAddon": false
}
```

# Actor output Schema

## `homes` (type: `string`):

One item per home for rent or for sale, with price, price per m², fees, area, rooms, location and photos.

## `summary` (type: `string`):

Per search: what ran or was skipped, homes listed and returned, and median price, price per m² (p25, p75), area and total monthly cost, split by exact and nearby matches.

# 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 = {
    "locations": [
        "Pinheiros, São Paulo"
    ],
    "maxRequests": 10,
    "detailsAddon": false
};

// Run the Actor and wait for it to finish
const run = await client.actor("ribtools/quintoandar-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 = {
    "locations": ["Pinheiros, São Paulo"],
    "maxRequests": 10,
    "detailsAddon": False,
}

# Run the Actor and wait for it to finish
run = client.actor("ribtools/quintoandar-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 '{
  "locations": [
    "Pinheiros, São Paulo"
  ],
  "maxRequests": 10,
  "detailsAddon": false
}' |
apify call ribtools/quintoandar-scraper --silent --output-dataset

```

## MCP server setup

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