# ChavesNaMão Property Scraper (`bovi/chavesnamao-scraper`) Actor

Collects real-estate listings from Chaves na Mão, Brazil. Returns listing URLs, title, transaction, type, price, area, room counts, address, taxes, description, and photos when available.

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

## Pricing

from $8.00 / 1,000 chavesnamão property scrapers

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

## ChavesNaMão Property Scraper

Collect public residential and commercial property listings from
[Chaves na Mão](https://www.chavesnamao.com.br/), a Brazilian property
marketplace. Search-page records include the listing ID and URL, title,
transaction type, property type, advertised price, area, address, city/state,
and the listing image when those values are present. Optional detail fetching
adds labelled useful and total areas, bedroom, suite, bathroom and garage
counts, condominium fee, IPTU, description, and property gallery.

The Actor reads server-rendered listing pages and does not require an account.
It omits fields that are not present on a listing instead of filling them with
empty values. The maxResults setting caps the total number of records stored
across the supplied URLs.

### Input

- searchUrls: one or more Chaves na Mão search-result URLs. The prefilled
  example searches properties for sale in São Paulo.
- listingUrls: optional full listing URLs. If supplied, the Actor fetches
  those detail pages instead of search pages.
- maxResults: maximum records to store; defaults to 50.
- includeDetails: fetch each search result detail page and add the fields
  available there; defaults to false.
- proxyConfiguration: optional Apify proxy configuration. Requests go
  directly to the site when the proxy is disabled or omitted.

Example input:

```json
{
  "searchUrls": [
    "https://www.chavesnamao.com.br/imoveis-a-venda/sp-sao-paulo/"
  ],
  "maxResults": 50,
  "includeDetails": true,
  "proxyConfiguration": {
    "useApifyProxy": false
  }
}
```

### Example output

This sample is taken from a public detail page:

```json
{
  "listingId": 44952122,
  "url": "https://www.chavesnamao.com.br/imovel/casa-a-venda-3-quartos-com-garagem-sp-sao-paulo-vila-albertina-1200m2-RS3700000/id-44952122/",
  "propertyTitle": "Casa com 3 quartos à venda na Rua Manuel de Arzão, Vila Albertina, São Paulo",
  "transaction": "SELL",
  "property_type": "Casa / Sobrado",
  "price": 3700000,
  "area_m2": 1200,
  "area_useful": 1200,
  "area_total": 1200,
  "bedrooms": 3,
  "suites": 1,
  "bathrooms": 4,
  "garages": 12,
  "address": "Rua Manuel De Arzão, 300, Vila Albertina, São Paulo / SP",
  "city": "São Paulo",
  "state": "SP",
  "iptu": 1145
}
```

### Price per result

Apify bills one dataset item for each property record the Actor stores. The
current USD rate per result is the pay-per-result rate configured for this
Actor in Apify Console; this code does not add a separate actor charge.

# Actor input Schema

## `searchUrls` (type: `array`):

Chaves na Mão property-search pages. Add one or more URLs copied from chavesnamao.com.br.

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

Optional full Chaves na Mão listing URLs. When provided, the Actor fetches these listings instead of search pages.

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

Maximum number of property records to store across the supplied URLs.

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

Fetch each listing page and add available areas, room counts, tax, description, and gallery images.

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

Optional Apify proxy settings. When disabled or omitted, requests go directly to chavesnamao.com.br.

## Actor input object example

```json
{
  "searchUrls": [
    "https://www.chavesnamao.com.br/imoveis-a-venda/sp-sao-paulo/"
  ],
  "listingUrls": [
    "https://www.chavesnamao.com.br/imovel/casa-a-venda-3-quartos-com-garagem-sp-sao-paulo-vila-albertina-1200m2-RS3700000/id-44952122/"
  ],
  "maxResults": 50,
  "includeDetails": false,
  "proxyConfiguration": {
    "useApifyProxy": true,
    "apifyProxyGroups": [
      "RESIDENTIAL"
    ]
  }
}
```

# Actor output Schema

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

Dataset containing the scraped property records.

# 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 = {
    "searchUrls": [
        "https://www.chavesnamao.com.br/imoveis-a-venda/sp-sao-paulo/"
    ],
    "proxyConfiguration": {
        "useApifyProxy": true,
        "apifyProxyGroups": [
            "RESIDENTIAL"
        ]
    }
};

// Run the Actor and wait for it to finish
const run = await client.actor("bovi/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 = {
    "searchUrls": ["https://www.chavesnamao.com.br/imoveis-a-venda/sp-sao-paulo/"],
    "proxyConfiguration": {
        "useApifyProxy": True,
        "apifyProxyGroups": ["RESIDENTIAL"],
    },
}

# Run the Actor and wait for it to finish
run = client.actor("bovi/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 '{
  "searchUrls": [
    "https://www.chavesnamao.com.br/imoveis-a-venda/sp-sao-paulo/"
  ],
  "proxyConfiguration": {
    "useApifyProxy": true,
    "apifyProxyGroups": [
      "RESIDENTIAL"
    ]
  }
}' |
apify call bovi/chavesnamao-scraper --silent --output-dataset

```

## MCP server setup

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