# ChavesNaMao City Property Listings Extractor (`vexaloom-labs/chavesnamao-city-property-listings-extractor`) Actor

Search ChavesNaMão for sale or rental properties in 15 major Brazilian cities, with price, condominium fee, IPTU, room counts, area and neighborhood for each listing.

- **URL**: https://apify.com/vexaloom-labs/chavesnamao-city-property-listings-extractor.md
- **Developed by:** [vexaloom-labs](https://apify.com/vexaloom-labs) (community)
- **Categories:** Real estate, Lead generation, Automation
- **Features:** Limited permissions
- **Stats:** 2 total users, 1 monthly users, 100.0% runs succeeded, 0 bookmarks
- **User rating**: No ratings yet

## Pricing

from $0.49 / 1,000 results

This Actor is paid per event and usage. You are charged both the fixed price for specific events and for Apify platform usage.
Since this Actor supports Apify Store discounts, the price gets lower the higher subscription plan you have.

Learn more: https://docs.apify.com/actors/running/actors-in-store.md#pay-per-event

## What's an Apify Actor?

An Actor is a serverless cloud program that runs on the Apify platform. It has two run modes.
In Batch mode, an Actor accepts a well-defined JSON input, performs an action which can take anything from a few seconds to a few hours,
and optionally produces a well-defined JSON output, datasets with results, or files in key-value store.
In Standby mode, an Actor provides a web server which can be used as a website, API, or an MCP server.

Apify vocabulary and the platform model are defined once, in the agent quickstart at https://apify.com/agents.md.

## How to integrate an Actor?

If asked about integration, you help developers integrate Actors into their projects.
You adapt to their stack and deliver integrations that are safe, well-documented, and production-ready.

Do not guess an integration path. Every one of them is in the agent quickstart at https://apify.com/agents.md: the Apify MCP server, Agent Skills with the Apify CLI, the JavaScript and Python clients, the REST API, and the account-free path for an agent with no human to sign in. It also carries the rule on stating cost before the first paid run.

For examples already wired to this Actor's own input schema, see the [API](#api) section below.

Each client library has reference documentation the quickstart does not restate: [JavaScript/TypeScript](https://docs.apify.com/api/client/js/docs.md) (`npm install apify-client`) and [Python](https://docs.apify.com/api/client/python/docs.md) (`pip install apify-client`).

# README

## ChavesNaMao City Property Listings Extractor

ChavesNaMão is one of Brazil's busiest property portals, with hundreds of thousands of sale and rental ads in a single city. This actor reads those listings without cookies or login, applies the portal's own filters, walks its result pages, and can open each ad to return the full published details.

### What it collects

- Sale (venda) and rental (aluguel) listings in 17 major Brazilian cities.
- Structured search by property type, price range, area range, minimum bedrooms, bathrooms and parking spaces, advertiser type and sort order.
- Every result page, with duplicate listing IDs removed, up to the requested limit.
- Optional detail enrichment for each listing: full description, publisher name, CRECI and phone, complete photo list, amenities, video and 360° tour links, publication and update dates.

Fields are omitted when ChavesNaMão does not publish them for a particular ad. The actor never writes null, empty-string or placeholder values.

### Input defaults

| Input | Default | Notes |
| --- | --- | --- |
| `collectionMode` | `listings` | `details` for known ads. |
| `transactionType` | `sell` | `rent` for aluguel. |
| `city` | `sao-paulo` | One of 17 built-in city slugs. |
| `propertyType` | `all` | Every type when not restricted. |
| `bedroomsMin` | 0 | No minimum. |
| `bathroomsMin` | 0 | No minimum. |
| `garagesMin` | 0 | No minimum. |
| `priceMin` | – | No minimum. |
| `priceMax` | – | No maximum. |
| `areaMin` | – | No minimum. |
| `areaMax` | – | No maximum. |
| `sortBy` | `relevance` | Site default order. |
| `ownerType` | `all` | All advertisers. |
| `maxItems` | 20 | Daily-test prefill uses 3. |
| `maxPages` | 34 | 30 rows per page. |
| `includeDetails` | false | One extra request per listing. |
| `listingUrls` | – | Any ChavesNaMão search URL. |
| `propertyUrls` | – | Details mode only. |
| `propertyIds` | – | Details mode only. |

### Collection modes

#### Search listings

Choose a transaction, city and any combination of filters. The actor translates them into the same filter syntax the ChavesNaMão website uses, then follows the selected sort order across pages.

| Input | Meaning |
| --- | --- |
| `transactionType` | `sell` for venda, `rent` for aluguel. |
| `city` | One of the 17 built-in city slugs. |
| `propertyType` | All types or one of apartments, houses, gated houses, kitnets, penthouses, flats, lofts, commercial rooms/houses/points, buildings, warehouses, land, chácaras, farms or garages. |
| `bedroomsMin`, `bathroomsMin`, `garagesMin` | Minimum room counts. 0 means no minimum. |
| `priceMin`, `priceMax`, `areaMin`, `areaMax` | Numeric bounds in BRL and square metres. |
| `sortBy` | Relevance, newest, price ascending/descending, area ascending/descending. |
| `ownerType` | All advertisers, direct with owner, or agencies only. |
| `maxItems` | Total listings to save (1–1000). |
| `maxPages` | Pages to request per search, 30 listings each. |
| `includeDetails` | Add one detail request per listing for the richer fields. |
| `listingUrls` | Optional ChavesNaMão search URLs, used verbatim. Any city or neighbourhood reachable on the site can be scraped this way. |

#### Property details

Set `collectionMode` to `details` and provide `propertyIds`, `propertyUrls`, or both. Each ad is fetched from ChavesNaMão's detail endpoint and returned once. This is the cheapest way to refresh a known shortlist.

### Output per listing

| Field | Description |
| --- | --- |
| `propertyId` | ChavesNaMão listing ID. |
| `title` | Listing title as published. |
| `transactionType` | `SELL` or `RENT`. |
| `price`, `priceCurrency`, `priceDisplay` | Numeric asking price, currency and the original formatted text. |
| `condominiumFee`, `condominiumFeeValue` | Monthly condominium fee text and numeric value when available. |
| `iptuValue`, `iptuValueNumeric` | Annual IPTU property-tax text and numeric value when available. |
| `propertyType`, `propertyTypeId`, `propertyTypeSlug` | Property category. |
| `bedrooms`, `bedroomsMax` | Bedrooms (minimum and maximum when the ad publishes a range). |
| `bathrooms`, `bathroomsMax` | Bathrooms. |
| `suites`, `suitesMax` | En-suite bedrooms. |
| `garages`, `garagesMax` | Garage or parking spaces. |
| `commercialRooms`, `commercialRoomsMax` | Commercial rooms when applicable. |
| `areaSqM`, `usableAreaSqM`, `totalAreaSqM` | Primary, usable and total area in square metres. |
| `street`, `addressNumber`, `neighborhood`, `neighborhoodId` | Address details. |
| `city`, `cityId`, `stateAcronym`, `state`, `zipCode` | Location details. |
| `latitude`, `longitude` | Coordinates when the ad or neighbourhood supplies them. |
| `publicAddress` | Whether the full street address is public on the ad. |
| `description` | Full description (HTML stripped, up to 5,000 characters). |
| `reference` | Advertiser's internal reference code. |
| `petFriendly`, `acceptTrade`, `active`, `highlighted` | Booleans published by the ad. |
| `publisherName`, `publisherType`, `publisherCreci`, `publisherVerified` | Advertiser identity. |
| `publisherPhone`, `publisherWhatsApp`, `publisherUrl` | Advertiser contact details and profile link. |
| `imageCount`, `featuredImage`, `imageUrls` | Photo count and full-resolution image links. |
| `videoUrl`, `tour360Url` | Video and virtual-tour links. |
| `amenities`, `buildingAmenities` | Private and common-area features from the detail page. |
| `createdAt`, `updatedAt` | Publication and last-update timestamps. |
| `propertyUrl` | Direct link to the ad. |
| `scrapedAt` | ISO timestamp of collection. |

### Examples

Three apartments for sale in São Paulo with the daily-test prefill:

```json
{
  "collectionMode": "listings",
  "transactionType": "sell",
  "city": "sao-paulo",
  "maxItems": 3,
  "maxPages": 1
}
```

Rentals in Rio de Janeiro between R$ 2,000 and R$ 4,000, at least two bedrooms, newest first, with full details:

```json
{
  "collectionMode": "listings",
  "transactionType": "rent",
  "city": "rio-de-janeiro",
  "bedroomsMin": 2,
  "priceMin": 2000,
  "priceMax": 4000,
  "sortBy": "newest",
  "maxItems": 50,
  "includeDetails": true
}
```

Houses for sale in a neighbourhood using the site's own URL:

```json
{
  "collectionMode": "listings",
  "listingUrls": ["https://www.chavesnamao.com.br/casas-a-venda/sp-sao-paulo/pinheiros/"],
  "maxItems": 100
}
```

Full details for known ads:

```json
{
  "collectionMode": "details",
  "propertyUrls": ["https://www.chavesnamao.com.br/imovel/apartamento-a-venda-2-quartos-sp-sao-paulo-pinheiros-90m2-RS750000/id-26583048/"]
}
```

### Compatibility with older tasks

Older tasks that send `mode` as `sell` or `rent`, plus `city` and `maxItems`, keep working: the actor reads those hidden legacy keys and maps them to `transactionType` and listings mode. The schema exposes `collectionMode` for new tasks. Existing output fields are unchanged; the revamp only adds fields beside them.

### FAQ

**Do I need a ChavesNaMão account or cookies?**
No. The actor reads the same public pages and JSON endpoints shown to any visitor, with no login, cookie or proxy input.

**Can I search several cities at once?**
Yes. Pass several `listingUrls` (one per city) in a single run. When no URL is supplied, one city is searched from the `city` control.

**How many listings can one search return?**
ChavesNaMão reports hundreds of thousands of ads per large city and currently exposes up to 333 pages (about 10,000 rows) per search. Set `maxItems` and `maxPages` to the depth you need. Larger total volumes are reached by splitting the query with price, area or neighbourhood filters.

**Why are some fields missing from a row?**
ChavesNaMão does not publish every detail for every ad. Empty values are omitted rather than fabricated. Turn on `includeDetails` to fill the detail-only fields for the listings that have them.

**Are condominium fee and IPTU numbers or text?**
Both are kept as the original display text (`condominiumFee`, `iptuValue`) and, when parseable, also as numbers (`condominiumFeeValue`, `iptuValueNumeric`).

**What does `publicAddress` mean?**
When true, the ad shows the street and number publicly. When false or absent, the portal hides the exact address even though the neighbourhood is known.

**Is this affiliated with ChavesNaMão?**
No. This is an independent data tool and is not affiliated with, endorsed by or sponsored by ChavesNaMão.

# Actor input Schema

## `collectionMode` (type: `string`):

Search listings by city and filters, or fetch full details for specific ChavesNaMão listings.

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

Whether to search properties for sale (venda) or for rent (aluguel).

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

Brazilian city to search in listings mode. For any other city, paste one of its ChavesNaMão search URLs into Listing URLs.

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

Restrict the search to one property type, or search every type.

## `bedroomsMin` (type: `integer`):

Minimum number of bedrooms (quartos). Use 0 for no minimum.

## `bathroomsMin` (type: `integer`):

Minimum number of bathrooms (banheiros). Use 0 for no minimum.

## `garagesMin` (type: `integer`):

Minimum number of garage or parking spaces (vagas). Use 0 for no minimum.

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

Minimum asking price in Brazilian reais. Leave empty for no minimum.

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

Maximum asking price in Brazilian reais. Leave empty for no maximum.

## `areaMin` (type: `integer`):

Minimum usable area in square metres. Leave empty for no minimum.

## `areaMax` (type: `integer`):

Maximum usable area in square metres. Leave empty for no maximum.

## `sortBy` (type: `string`):

Order of the listing results.

## `ownerType` (type: `string`):

Show every advertiser, only listings direct from the owner, or only real-estate agencies.

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

Maximum number of listings to save across all selected searches (1–1000).

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

Maximum result pages to request for each search (30 listings per page). Stops earlier when the source runs out.

## `includeDetails` (type: `boolean`):

Fetch each listing's detail page data: full description, publisher phone and CRECI, photo list, amenities, video and tour links, created and updated dates. Costs one extra request per listing.

## `listingUrls` (type: `array`):

Optional ChavesNaMão search URLs to scrape exactly as configured on the site. Use this for cities, neighbourhoods or filter combinations not covered by the controls above.

## `propertyUrls` (type: `array`):

ChavesNaMão property URLs to fetch in details mode (they contain an id-<number> segment).

## `propertyIds` (type: `array`):

ChavesNaMão listing IDs to fetch in details mode. Property URLs also work.

## Actor input object example

```json
{
  "collectionMode": "listings",
  "transactionType": "sell",
  "city": "sao-paulo",
  "propertyType": "all",
  "bedroomsMin": 0,
  "bathroomsMin": 0,
  "garagesMin": 0,
  "sortBy": "relevance",
  "ownerType": "all",
  "maxItems": 3,
  "maxPages": 1,
  "includeDetails": false
}
```

# Actor output Schema

## `listings` (type: `string`):

Dataset containing every scraped ChavesNaMão property 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 = {
    "collectionMode": "listings",
    "transactionType": "sell",
    "city": "sao-paulo",
    "maxItems": 3,
    "maxPages": 1,
    "includeDetails": false
};

// Run the Actor and wait for it to finish
const run = await client.actor("vexaloom-labs/chavesnamao-city-property-listings-extractor").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 = {
    "collectionMode": "listings",
    "transactionType": "sell",
    "city": "sao-paulo",
    "maxItems": 3,
    "maxPages": 1,
    "includeDetails": False,
}

# Run the Actor and wait for it to finish
run = client.actor("vexaloom-labs/chavesnamao-city-property-listings-extractor").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 '{
  "collectionMode": "listings",
  "transactionType": "sell",
  "city": "sao-paulo",
  "maxItems": 3,
  "maxPages": 1,
  "includeDetails": false
}' |
apify call vexaloom-labs/chavesnamao-city-property-listings-extractor --silent --output-dataset

```

## MCP server setup

```json
{
    "mcpServers": {
        "apify": {
            "type": "http",
            "url": "https://mcp.apify.com/?tools=fetch-actor-details,vexaloom-labs/chavesnamao-city-property-listings-extractor"
        }
    }
}
```

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/9DHzfXPbmN43uWYSH/builds/h8qsnYHHOCBNfp8bD/openapi.json
