# Chaves na Mão Property Listings (`bovi/chaves-scraper`) Actor

Scrape Chaves na Mão property listings. Get IDs, URLs, titles, locations, prices, and property details from cards. Run with deal_type and location; no buyer login or API key. Pricing: $0.0015 per dataset item + $0.00005 per Actor Start on Free.

- **URL**: https://apify.com/bovi/chaves-scraper.md
- **Developed by:** [Vitalii Bondarev](https://apify.com/bovi) (community)
- **Categories:** Real estate, Automation, Developer tools
- **Features:** Limited permissions
- **Stats:** 2 total users, 1 monthly users, 100.0% runs succeeded, 0 bookmarks
- **User rating**: No ratings yet

## Pricing

from $1.50 / 1,000 chaves na mão property 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

## Chaves na Mão Property Listings Scraper

Scrape public property listing cards from [Chaves na Mão](https://www.chavesnamao.com.br/) for Brazilian locations, covering sale, rent, or both. On the Free plan, billing is $0.0015 per dataset item plus $0.00005 per Actor Start event.

- Extract listing IDs, URLs, titles, prices, locations, and property details shown on each result card.
- Compare sale, rental, or combined inventory by location.
- Build property datasets for market research, listing discovery, or inventory monitoring.
- Keep optional card fields omitted when Chaves na Mão does not display them.
- Run with your Apify account without a buyer-owned source login or API-key input.

### What you get

The Actor searches a selected location, follows the source result pages, removes repeated listing IDs, and saves up to the requested maximum. Each record contains card-visible values only. `id`, `url`, and `title` are included for emitted listings; the other fields are optional and can be omitted when the card does not show them.

| Field | Type | Description | Availability |
| --- | --- | --- | --- |
| `id` | string | Source listing identifier from the listing card URL. | Included |
| `url` | string | Chaves na Mão listing URL. | Included |
| `title` | string | Listing title. | Included |
| `deal_type` | string | Transaction type, such as `sale` or `rent`. | Optional |
| `property_type` | string | Property type, such as `Casa` or `Apartamento`. | Optional |
| `location` | string | Location displayed on the card. | Optional |
| `price_brl` | number | Numeric price in Brazilian reais. | Optional |
| `price_text` | string | Price text displayed on the card. | Optional |
| `area_m2` | number | Property area in square metres. | Optional |
| `bedrooms` | integer | Number of bedrooms or dormitories shown. | Optional |
| `bathrooms` | integer | Number of bathrooms shown. | Optional |
| `parking_spaces` | integer | Number of parking spaces or garages shown. | Optional |
| `image_url` | string | Card image URL when an image is present. | Optional |

The Actor does not add contact details or other values that are not present in the search result card.

### Sample output

```json
{
  "id": "28942505",
  "url": "https://www.chavesnamao.com.br/imovel/casa-a-venda-2-quartos-com-garagem-sp-sao-paulo-chacara-california-60m2-RS420000/id-28942505/",
  "title": "Casa com 2 dormitórios à venda por R$ 420.000,00 - Chácara Califórnia - São Paulo/SP",
  "deal_type": "sale",
  "property_type": "Casa",
  "location": "Chácara Califórnia, São Paulo/SP",
  "area_m2": 60,
  "bedrooms": 2,
  "bathrooms": 2,
  "parking_spaces": 1,
  "price_text": "R$ 420.000",
  "price_brl": 420000,
  "image_url": "https://www.chavesnamao.com.br/imn/0400X0262/N/60/imoveis/770893/28942505/sp-sao-paulo-chacara-california-rua-francisco-machado-de-campos-casa-sobrado-a-venda-2-quartos-67cbb054-1.jpg"
}
```

### Pricing

This Actor uses pay-per-event billing. The Actor charges for the following events on the Free plan:

| Event | What it represents | Price on Free |
| --- | --- | --- |
| `apify-default-dataset-item` | One scraped result with all fields available on that card. | $0.0015 per event on the Free plan |
| `apify-actor-start` | The Actor starting a run. | $0.00005 per event on the Free plan |

The number of Actor Start events depends on Actor memory, with one event per GB and a minimum of one event. A worked example is **1,000 results = $1.50 on Free** in dataset-item charges and **10,000 results = $15 on Free** in dataset-item charges; the separate Actor Start event is billed at $0.00005 on Free.

The Apify Free plan includes **$5 per month of platform usage credit**. Using the supplied Free-plan calculation, that covers **3,333 dataset-item results** after one $0.00005 Actor Start event.

Platform usage is separate from the Actor’s event definitions: compute, Apify Proxy traffic including residential traffic, and storage are included in the event prices and paid by the Actor developer. This pricing setup does not pass separate platform-usage charges to the buyer.

### How to use

1. **Open** the Chaves na Mão Property Listings Actor in Apify.
2. **Choose** `sale`, `rent`, or `all` for `deal_type`.
3. **Enter** a location as a city with its two-letter state code, a state code, or `Brasil`.
4. **Set** `maxResults` to the maximum number of listing records to save, from `1` to `1000`.
5. **Configure** `proxyConfiguration` if needed, or omit it for a direct connection. Setting `useApifyProxy` to `true` creates an Apify proxy configuration.
6. **Run** the Actor and inspect the resulting dataset for listing cards and optional fields.
7. **Repeat** the run through Apify Schedules; daily is a suitable starting point for listing collection.

Example input:

```json
{
  "deal_type": "all",
  "location": "São Paulo, SP",
  "maxResults": 50,
  "proxyConfiguration": {
    "useApifyProxy": true,
    "apifyProxyGroups": ["RESIDENTIAL"]
  }
}
```

Export the dataset as JSON or CSV, or read it through the Apify dataset API.

### Input parameters

| Parameter | What it does | Default |
| --- | --- | --- |
| `deal_type` | Selects sale listings, rental listings, or both. Accepted values are `sale`, `rent`, and `all`. | `sale` |
| `location` | Selects the search location. Use a city and two-letter state code, a state code, or `Brasil`. | `São Paulo, SP` |
| `maxResults` | Sets the maximum number of listing records to save. The documented range is `1` to `1000`. | `50` |
| `proxyConfiguration` | Optional Apify proxy settings. With `useApifyProxy: true`, the Actor creates an Apify proxy configuration; omit it or set `useApifyProxy` to `false` for a direct connection. | Apify proxy configuration in the schema; direct connection when omitted in a request |

### Limits and edge cases

| Condition | What the buyer sees | What to do |
| --- | --- | --- |
| `maxResults` is outside the documented `1` to `1000` range | The value is outside the input schema’s documented range. | Use an integer from `1` through `1000`. |
| `maxResults` is `0` or less | The Actor logs that no records were requested and ends without saving records. | Set `maxResults` to a positive integer. |
| The first fetched page contains no listing cards | The run raises an error stating that the response contained no listing cards. | Check the location format and try the search again. |
| A page request fails | The request is attempted up to three times. If all attempts fail, the run raises a runtime error. | Check the location and proxy configuration, then retry the run. |
| A later page fails after earlier records were saved | Records pushed before the failure remain in the dataset, but the run does not continue to later records. | Review the partial dataset and retry if more results are needed. |
| The search has more than 100 result pages | The Actor stops after 100 pages to avoid an unbounded run. | Narrow the location or run a separate search if the requested inventory is larger. |
| A listing card does not show a field | That field is omitted from the record rather than added with a value. | Treat optional fields as nullable or missing when processing the dataset. |
| The same listing ID appears more than once across result pages | The repeated listing is saved only once. | Use `id` as the listing identifier when deduplicating downstream data. |
| Fewer listings are available than `maxResults` | The dataset contains fewer records than the requested maximum. | Check the selected location and transaction type, or broaden the search. |

### FAQ

#### How much does it cost to scrape Chaves na Mão property listings?

On the Free plan, dataset items cost $0.0015 each and Actor Start events cost $0.00005 each. For example, **1,000 results = $1.50 on Free** in dataset-item charges, with the separate Actor Start event charged on Free as described in the Pricing section.

#### What happens if the Actor returns an empty result?

If the first fetched page contains no listing cards, the run raises an error and recommends checking the location. Verify the city and state format, transaction type, and spelling, then run the search again.

#### What should I do if a run is not working?

A failed page request is retried up to three times. If the request still fails, check the location and proxy configuration and retry the run. If a later page fails, records already pushed before that point can remain available in the dataset.

#### Why are some fields missing from a listing?

The Actor extracts values visible on the search result card. Since card details vary, fields such as price, area, bathrooms, parking spaces, or the image URL are omitted when they are not shown.

#### Is scraping this public data legal or allowed?

The Actor collects public listing-card data from Chaves na Mão. Source terms and applicable law depend on the buyer’s use case, so review the relevant terms and legal requirements before using the data.

# Actor input Schema

## `deal_type` (type: `string`):

Choose sale listings, rental listings, or both.

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

Use a city and two-letter state code (for example, São Paulo, SP), a state code, or Brasil.

## `maxResults` (type: `integer`):

Maximum number of listing records to save.

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

Optional Apify proxy settings. Omit this or set useApifyProxy to false to connect directly.

## Actor input object example

```json
{
  "deal_type": "sale",
  "location": "São Paulo, SP",
  "maxResults": 50,
  "proxyConfiguration": {
    "useApifyProxy": true,
    "apifyProxyGroups": [
      "RESIDENTIAL"
    ]
  }
}
```

# Actor output Schema

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

Dataset with the collected property listings.

# 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 = {
    "deal_type": "sale",
    "location": "São Paulo, SP",
    "proxyConfiguration": {
        "useApifyProxy": true,
        "apifyProxyGroups": [
            "RESIDENTIAL"
        ]
    }
};

// Run the Actor and wait for it to finish
const run = await client.actor("bovi/chaves-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 = {
    "deal_type": "sale",
    "location": "São Paulo, SP",
    "proxyConfiguration": {
        "useApifyProxy": True,
        "apifyProxyGroups": ["RESIDENTIAL"],
    },
}

# Run the Actor and wait for it to finish
run = client.actor("bovi/chaves-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 '{
  "deal_type": "sale",
  "location": "São Paulo, SP",
  "proxyConfiguration": {
    "useApifyProxy": true,
    "apifyProxyGroups": [
      "RESIDENTIAL"
    ]
  }
}' |
apify call bovi/chaves-scraper --silent --output-dataset

```

## MCP server setup

```json
{
    "mcpServers": {
        "apify": {
            "type": "http",
            "url": "https://mcp.apify.com/?tools=fetch-actor-details,bovi/chaves-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/CfDNtD7HIb38zndpx/builds/fWd30CVOWblBbVjYg/openapi.json