# Chaves na Mão Scraper - Brazil Real Estate Listings (`igolaizola/chavesnamao-scraper`) Actor

Scrape Chaves na Mão listings at chavesnamao.com.br across Brazil for sale or rent. Filter by location, coordinates, price, area, property type, amenities, advertiser, and nearby places, then export clean results to JSON, CSV, or Excel for market research, pricing, and lead generation.

- **URL**: https://apify.com/igolaizola/chavesnamao-scraper.md
- **Developed by:** [Iñigo Garcia Olaizola](https://apify.com/igolaizola) (community)
- **Categories:** Real estate, Lead generation, Automation
- **Stats:** 3 total users, 2 monthly users, 100.0% runs succeeded, 0 bookmarks
- **User rating**: No ratings yet

## Pricing

from $0.70 / 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?

Actors are web data automations that power AI and operations. They run on the Apify platform to scrape websites, process data, connect APIs, and automate workflows.
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.
Actors are written with capital "A".

## 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.
The best way to integrate Actors is as follows.

- **AI agents and MCP clients** — the [Apify MCP server](https://docs.apify.com/integrations/mcp.md) at `https://mcp.apify.com` (remote, streamable HTTP, OAuth on first use).
- **Agentic workflows and local Actor development** — [Agent Skills](https://apify.com/.well-known/agent-skills/index.json) with the [Apify CLI](https://docs.apify.com/cli/docs.md): `npm install -g apify-cli`, then `apify login`.
- **JavaScript/TypeScript projects** — the official [JS/TS client](https://docs.apify.com/api/client/js/docs.md): `npm install apify-client`.
- **Python projects** — the official [Python client](https://docs.apify.com/api/client/python/docs.md): `pip install apify-client`.
- **Any other language** — the [REST API](https://docs.apify.com/api/v2.md).

For usage examples, see the [API](#api) section below.

For more details, see Apify documentation as [Markdown index](https://docs.apify.com/llms.txt) and [Markdown full-text](https://docs.apify.com/llms-full.txt).

# README

## Chaves na Mão Scraper — Brazil Real-Estate Listings & Filters

Collect Chaves na Mão property listings across Brazil for sale and rent. Compare prices, understand local inventory, and export structured real-estate data for research, pricing, and lead generation.

> SEO keywords: **Chaves na Mão scraper**, **Brazil real-estate listings**, **property data**, **sale and rent listings**, **Apify actor**.

### 🤖 What does Chaves na Mão Scraper do?

- Collect public property listings across Brazil.
- Search by a friendly city, zone, neighborhood, or street name.
- Use latitude and longitude to find the nearest city automatically.
- Filter by price, area, bedrooms, bathrooms, parking spaces, amenities, property type, new developments, nearby places, and advertiser.
- Choose listings for sale or rent and export a clean dataset as JSON, CSV, or Excel.

**Great for:** market research, rental and sale comparisons, price monitoring, inventory analysis, and real-estate lead generation.

### 💡 Why use Chaves na Mão?

- 📈 **Track price trends** — compare asking prices and property sizes across Brazilian locations.
- 🏘️ **Understand inventory** — segment listings by operation, property type, rooms, and amenities.
- 🎯 **Build useful datasets** — combine location and listing details for research or outreach.

### 🚀 Quick start in Apify

1. Open the actor in Apify Console and choose **Try for free**.
2. Choose **For sale** or **For rent**.
3. Set **Maximum listings**, then add a location or any filters you need.
4. Click **Start** and open the Dataset tab to view or export JSON, CSV, or Excel results.

### 📝 Input parameters

| Parameter | Type | Required | Description |
| --- | --- | --- | --- |
| `operation` | enum | Yes | `sale` for properties for sale or `rent` for properties to rent. |
| `maxItems` | integer | Yes | Maximum listings to collect. Set to `0` to request all available listings within the actor's result limit. |
| `fetchDetails` | boolean | No | Fetch the full structured details page for each listing and add it under `_details`. Uses one additional request per listing and may increase run time and cost. |
| `location` | string | No | Friendly city, zone, neighborhood, or street name. Example: `São Paulo`. When omitted, the search covers Brazil. |
| `locationType` | enum | No | Restrict matching to `city`, `zone`, `neighborhood`, or `street`. Leave empty for automatic matching. |
| `minPrice` / `maxPrice` | integer | No | Minimum and maximum price in Brazilian reais. |
| `minArea` / `maxArea` | integer | No | Minimum and maximum area in square metres. |
| `bedrooms` | integer | No | Minimum number of bedrooms. |
| `bathrooms` | integer | No | Minimum number of bathrooms. |
| `garages` | integer | No | Minimum number of parking spaces. |
| `amenities` | enum list | No | Selected amenities, such as `pool`, `elevator`, `air-conditioning`, `furnished`, `garden`, or `balcony`. |
| `propertyTypes` | enum list | No | Selected categories, such as `apartment`, `house`, `condominium`, `land`, or `studio`. |
| `launchOnly` | boolean | No | Limit results to new developments. |
| `nearbyPlaces` | enum list | No | Nearby `subway`, `parks`, or `shopping` places; the platform uses a fixed distance of up to 1 km. |
| `advertiser` | enum | No | `all`, `owner`, or `agency`. |
| `latitude` / `longitude` | number | No | Coordinate pair used to resolve the nearest city. Provide both values; coordinates take precedence over `location`. |

#### Example inputs

**Brazil-wide sale search**

```json
{
  "operation": "sale",
  "maxItems": 100
}
```

**Filtered São Paulo rental search**

```json
{
  "operation": "rent",
  "location": "São Paulo",
  "locationType": "city",
  "minPrice": 1800,
  "maxPrice": 5000,
  "bedrooms": 2,
  "amenities": ["pool", "elevator"],
  "propertyTypes": ["apartment"],
  "nearbyPlaces": ["subway"],
  "advertiser": "agency",
  "fetchDetails": true,
  "maxItems": 50
}
```

### 🧭 Tips and recipes

- **Review a small sample first:** start with `maxItems` between 25 and 100.
- **Collect the full available set:** set `maxItems` to `0`; the actor's result limit still applies.
- **Search all of Brazil:** omit both `location` and coordinates.
- **Disambiguate a place name:** use `locationType` when a name could refer to more than one area.
- **Use coordinate search:** provide both `latitude` and `longitude`; no radius setting is required.
- **Include full listing details:** set `fetchDetails` to `true`; detail data is stored under `_details` and includes descriptions, photos, prices, publisher data, amenities, and timestamps when supplied by the listing.
- **Keep filters focused:** omitted filters are not applied, so add only the criteria you need.

### 📊 Output fields

- **id**, **url**, **title** — Listing identity and headline content.
- **transaction** — The listing transaction type returned by the site.
- **prices** — Price values and fees when supplied.
- **area**, **bedrooms**, **bathrooms**, **garages** — Property dimensions and room counts.
- **pictures** — Photos when supplied.
- **location** — Structured street, neighborhood, city, and state information when available.
- **publisher** — Advertiser name, verification status, and phone data when supplied.
- **\_details** — Included only when `fetchDetails` is enabled; contains the additional structured detail object returned for the listing.

```json
{
  "id": 26582605,
  "url": "https://www.chavesnamao.com.br/imovel/terreno-a-venda-sp-sao-paulo-jardim-claudia-889m2-RS2000000/id-26582605/",
  "title": "Terreno à venda, 889 m² por R$ 2.000.000,00 - Jardim Cláudia - São Paulo/SP",
  "transaction": "SELL",
  "prices": {"main": "R$ 2.000.000,00", "rawPrice": 2000000},
  "area": {"useful": "889", "total": "889"},
  "bedrooms": 0,
  "bathrooms": 0,
  "garages": 0,
  "pictures": {"featured": "https://www.chavesnamao.com.br/imn/1200x0800/N/70/imoveis/611560/26582605/sp-sao-paulo-jardim-claudia-rua-pixinguinha-terreno-a-venda-673c06a4-1.jpg"},
  "location": {"street": {"name": "Rua Pixinguinha"}, "city": {"name": "São Paulo"}, "state": {"acronym": "SP"}},
  "publisher": {"name": "Imobiliária Exemplo"}
}
```

### ❓ FAQ

#### Can I collect every available listing?

Yes. Set `maxItems` to `0`; the actor's result limit still applies. For a first run, a smaller limit is useful for checking the output shape.

#### Can I provide a location name instead of coordinates?

Yes. Add `location` with a city, zone, neighborhood, or street name. The actor chooses the best matching area; use `locationType` to narrow the match when needed.

#### What happens when I omit location and coordinates?

The actor searches across Brazil while preserving the selected operation and filters.

#### Can I export the results?

Yes. Apify Dataset supports JSON, CSV, Excel, and other standard export formats.

#### Does every listing include every field?

No. Native fields vary by listing. Price, photos, location, and room counts are included when the site supplies them; `_details` appears only when detail fetching is enabled.

### ⚖️ Legal and ethical considerations

- Follow Chaves na Mão’s terms and applicable Brazilian law.
- Collect and use public data responsibly, respecting privacy and data-protection requirements.
- Keep request rates reasonable and avoid unnecessary repeated runs.
- Do not misrepresent your identity or use collected data for abusive contact.
- This independent Actor is not affiliated with, endorsed by, or sponsored by Chaves na Mão.

### 🛟 Support

Need help with the actor? Contact [igolaizola.com/#contact](https://igolaizola.com/#contact).

# Actor input Schema

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

Maximum number of property listings to collect. Set to 0 to request all available listings, subject to actor result limits.

## `fetchDetails` (type: `boolean`):

Fetch the full structured details page for each collected listing and add it under the \_details field. This uses one additional request per listing and may increase run time and cost.

## `operation` (type: `string`):

Choose whether to collect properties for sale or rent.

## `location` (type: `string`):

Optional city, zone, neighborhood, or street to search. Example: São Paulo. When omitted, the actor searches across Brazil. When provided, it selects the closest matching area and keeps the other search URL filters.

## `locationType` (type: `string`):

Optional category used to narrow location matches. Leave empty to let the actor choose the best category.

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

Only include listings priced at or above this amount in Brazilian reais. Leave empty for no minimum.

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

Only include listings priced at or below this amount in Brazilian reais. Leave empty for no maximum.

## `minArea` (type: `integer`):

Only include listings with at least this many square metres of area.

## `maxArea` (type: `integer`):

Only include listings with at most this many square metres of area.

## `bedrooms` (type: `integer`):

Only include listings with at least this many bedrooms.

## `bathrooms` (type: `integer`):

Only include listings with at least this many bathrooms.

## `garages` (type: `integer`):

Only include listings with at least this many parking spaces.

## `amenities` (type: `array`):

Only include listings with the selected amenities.

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

Only include the selected property types.

## `launchOnly` (type: `boolean`):

Only include properties in developments that are under construction, planned, or ready to move into.

## `nearbyPlaces` (type: `array`):

Only include listings near the selected place categories. The platform uses a fixed distance of up to 1 km.

## `advertiser` (type: `string`):

Choose whether to include all advertisers, only property owners, or only real-estate agencies.

## `latitude` (type: `number`):

Latitude used to resolve the nearest city. Provide together with longitude; coordinates take precedence over location text. Example: -23.55052 for São Paulo.

## `longitude` (type: `number`):

Longitude used to resolve the nearest city. Provide together with latitude; coordinates take precedence over location text. Example: -46.633309 for São Paulo.

## Actor input object example

```json
{
  "maxItems": 100,
  "fetchDetails": false,
  "operation": "sale",
  "location": "",
  "locationType": "",
  "amenities": [],
  "propertyTypes": [],
  "launchOnly": false,
  "nearbyPlaces": [],
  "advertiser": "all"
}
```

# Actor output Schema

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

No description

# 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 = {};

// Run the Actor and wait for it to finish
const run = await client.actor("igolaizola/chavesnamao-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 = {}

# Run the Actor and wait for it to finish
run = client.actor("igolaizola/chavesnamao-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 '{}' |
apify call igolaizola/chavesnamao-scraper --silent --output-dataset

```

## MCP server setup

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