Chaves na Mão Scraper

Slug: fatihtahta/chaves-na-mao-scraper

Overview

Chaves na Mão Scraper collects structured real estate listing data from Chaves na Mão, including listing identifiers, pricing breakdowns, location details, property characteristics, seller details, media assets, lead-channel settings, and nearby places. It turns location-based searches and filters into clean JSON records that are ready for analysis, reporting, and downstream systems. Chaves na Mão is one of Brazil's widely used property marketplaces, making it a valuable source for housing supply, pricing visibility, and local market research. The actor automates repetitive collection work so teams do not have to search, copy, and normalize listing data by hand. The result is a more consistent dataset and less operational time spent on recurring data collection.

Why Use This Actor

• Market researchers and analysts: Track listing volume, asking prices, property mix, and neighborhood trends across cities or segments.
• Product and content teams: Build local market pages, comparison content, and property datasets with structured listing, pricing, and media fields.
• Developers and data engineers: Feed ETL jobs, warehouses, internal dashboards, and enrichment workflows with normalized listing records.
• Lead generation and enrichment teams: Identify active listings, agencies, and seller details for CRM enrichment, outreach research, or territory mapping.
• Monitoring and competitive tracking teams: Watch changes in supply, pricing, below-market opportunities, and transit-friendly inventory over time.

Input Parameters

Provide a location plus any optional filters. The actor resolves a city, neighborhood, district, avenue, or street into the correct Chaves na Mão search flow and then collects normalized listing records from those result pages.

Parameter	Type	Description	Default
deal_type	string	Whether to collect all deals, sale listings, or rent listings. Allowed values: all, sale, rent.	sale
location	string	A place name or address-style query in Brazil, such as a city, neighborhood, district, avenue, or street.	–
sort_by	string	Sort order for result pages. Allowed values: most_relevant, most_recent, lowest_price, highest_price, smallest_area, largest_area.	most_relevant
property_type	array[string]	One or more property types to include. Allowed values: apartment, studio, kitnet, house, gated_house, villa_house, penthouse, flat, loft, residential_land, townhouse, farm, small_farm, store, office, commercial_house, hotel, corporate_floor, building, commercial_land, condominium_land, storage, garage, commercial, commercial_point.	–
amenities	array[string]	One or more amenities to require. Allowed values: air_conditioning, planned_cabinets, elevator, hydromassage, fireplace, furnished, sauna, balcony.	–
min_bedroom	string	Minimum bedroom count to include. Allowed values: 1, 2, 3, 4 for 1+, 2+, 3+, or 4+ bedrooms.	–
min_bathroom	string	Minimum bathroom count to include. Allowed values: 1, 2, 3, 4 for 1+, 2+, 3+, or 4+ bathrooms.	–
min_parking	string	Minimum parking spaces to include. Allowed values: 1, 2, 3, 4 for 1+, 2+, 3+, or 4+ spaces.	–
min_price	integer	Minimum listing price to include. Use whole numbers such as 400000.	–
max_price	integer	Maximum listing price to include. Use whole numbers such as 3000000.	–
below_market_price	boolean	When true, keeps only listings marked as below market price.	false
min_sqm	integer	Minimum usable area in square meters.	–
max_sqm	integer	Maximum usable area in square meters.	–
near_transit	boolean	When true, keeps only listings tagged as near transit access.	false
maximize_coverage	boolean	When true, checks reported counts before deep pagination and recursively splits oversized searches into exact price ranges until every branch is under the safe threshold.	false
limit	integer	Maximum number of listings to save for the run. Leave empty to collect all available results for the selected search.	–

The actor uses Apify Residential proxies in Brazil internally for every run, so proxyConfiguration is not exposed as an input parameter.

Example Inputs

Scenario: All deals with an amenity filter

{
  "deal_type": "all",
  "location": "Curitiba",
  "amenities": ["balcony"],
  "limit": 100
}

Scenario: Broad city sale search

{
  "deal_type": "sale",
  "location": "Sao Paulo",
  "sort_by": "lowest_price",
  "property_type": ["apartment", "house", "commercial"],
  "amenities": ["air_conditioning", "balcony"],
  "min_price": 400000,
  "max_price": 1500000,
  "limit": 250
}

Scenario: Rental search with commuter-friendly filters

{
  "deal_type": "rent",
  "location": "Pinheiros, Sao Paulo",
  "sort_by": "most_recent",
  "property_type": ["apartment", "studio", "flat"],
  "amenities": ["furnished"],
  "min_bedroom": "1",
  "near_transit": true,
  "max_price": 6000,
  "limit": 150
}

Scenario: Targeted below-market shortlist

{
  "deal_type": "sale",
  "location": "Belo Horizonte",
  "property_type": ["apartment"],
  "min_bathroom": "2",
  "below_market_price": true,
  "min_sqm": 70,
  "max_sqm": 120,
  "limit": 100
}

Output

The actor writes one normalized property_listing item per dataset row. Records use a stable real-estate contract with grouped public fields for BI, ETL, CRM, and AI workflows.

Recommended deduplication keys:

• record_id for upserts.
• source_context.external_ids.id for the source primary ID.
• entity.external_ids.id for secondary joins.

Example listing record

This is a representative Chaves na Mão output record based on a real listing shape:

{
  "record_type": "property_listing",
  "record_id": "41518750",
  "source_context": {
    "source_name": "Chaves na Mão",
    "source_domain": "chavesnamao.com.br",
    "source_site": "chavesnamao.com.br",
    "source_url": "https://www.chavesnamao.com.br/imoveis/brasil/",
    "canonical_url": "https://www.chavesnamao.com.br/imovel/sala-comercial-a-venda-126m2-rs1850000/id-41518750/",
    "loaded_url": "https://www.chavesnamao.com.br/imoveis/sp-sao-paulo/",
    "search_url": "https://www.chavesnamao.com.br/imoveis/sp-sao-paulo/",
    "listing_url": "https://www.chavesnamao.com.br/imovel/sala-comercial-a-venda-126m2-rs1850000/id-41518750/",
    "seed_type": "location",
    "seed_id": "2af1977af04a",
    "seed_value": "Sao Paulo",
    "page_index": 1,
    "external_ids": {
      "id": "41518750",
      "listing_id": "41518750",
      "external_id": "41518750",
      "legacy_id": "673379"
    }
  },
  "entity": {
    "title": "Andar / meia laje Comercial com 126 m² em Venda e Aluguel, Cerqueira César - SP",
    "name": "Andar / meia laje Comercial com 126 m² em Venda e Aluguel, Cerqueira César - SP",
    "headline": "Andar / meia laje Comercial com 126 m² em Venda e Aluguel",
    "description": "Imóvel comercial de 126 m² disponível para venda e aluguel em Cerqueira César.",
    "status": "active",
    "category": "commercial",
    "url": "https://www.chavesnamao.com.br/imovel/sala-comercial-a-venda-126m2-rs1850000/id-41518750/",
    "external_ids": {
      "id": "41518750",
      "external_id": "41518750",
      "legacy_id": "673379",
      "source_id": "673379"
    }
  },
  "listing": {
    "listing_id": "41518750",
    "listing_type": "used",
    "listing_status": "active",
    "transaction_type": "sell",
    "deal_type": "sale",
    "property_status": "ready",
    "is_featured": true,
    "is_sponsored": false,
    "is_new_listing": false,
    "posted_at": "2026-04-13T10:10:06",
    "updated_at": "2026-04-13T10:10:06",
    "listing_url": "https://www.chavesnamao.com.br/imovel/sala-comercial-a-venda-126m2-rs1850000/id-41518750/"
  },
  "pricing": {
    "price": 1850000,
    "price_text": "R$ 1.850.000",
    "price_numeric": 1850000,
    "currency": "BRL",
    "offers": [
      {
        "business_type": "sale",
        "amount": 1850000,
        "currency": "BRL",
        "monthly_condo_fee": "R$ 2.000",
        "iptu": "R$ 1.000"
      }
    ],
    "is_price_hidden": false
  },
  "location": {
    "address": {
      "label": "Avenida Paulista 1765, Bela Vista, São Paulo, SP",
      "full_address": "Avenida Paulista 1765, Bela Vista, São Paulo, SP",
      "street": "Avenida Paulista",
      "street_number": "1765",
      "neighborhood": "Bela Vista",
      "district": "Centro",
      "city": "São Paulo",
      "state": "São Paulo",
      "state_code": "SP",
      "country": "Brasil",
      "country_code": "BR",
      "postal_code": "01311-200",
      "address_complement": "ANDAR",
      "public_address": true
    },
    "full_address": "Avenida Paulista 1765, Bela Vista, São Paulo, SP",
    "street": "Avenida Paulista",
    "street_number": "1765",
    "neighborhood": "Bela Vista",
    "district": "Centro",
    "city": "São Paulo",
    "state": "São Paulo",
    "state_code": "SP",
    "country": "Brasil",
    "country_code": "BR",
    "postal_code": "01311-200",
    "coordinates": {
      "latitude": -23.56079,
      "longitude": -46.65786,
      "approximate": false,
      "source": "geocoder"
    },
    "nearby_places": {
      "bus_stops": [
        {
          "distance": 70,
          "name": "Avenida Paulista, 1754"
        }
      ],
      "hospitals": [
        {
          "distance": 310,
          "name": "Hospital 9 de Julho"
        }
      ],
      "restaurants": [
        {
          "distance": 40,
          "name": "McDonald's"
        }
      ]
    },
    "raw": {
      "legacy_location": {
        "label": "Avenida Paulista 1765, Bela Vista, São Paulo, SP"
      }
    }
  },
  "property": {
    "property_type": "conj_comercial_sala",
    "property_subtype": "REALTY",
    "property_status": "ready",
    "condition": "ready",
    "rooms": {
      "bedrooms": 0,
      "bathrooms": 2,
      "parking_spaces": 1,
      "commercial_rooms": 2
    },
    "floor_area": 126,
    "area": {
      "area": 126,
      "area_unit": "m²",
      "floor_area": 126,
      "usable_area": 126,
      "lot_area": 200,
      "total_area": 126
    },
    "property_taxonomy": {
      "name": "Conj. Comercial / Sala",
      "title_name": "Conj. Comercial / Salas",
      "id": 7,
      "url": "sala-comercial",
      "prefix": "deste"
    },
    "furnishing": "Semi furnished",
    "amenities": [
      "Elevador(es)",
      "Portaria"
    ],
    "features": {
      "private_items": [
        {
          "name": "Ar Condicionado",
          "id": 5
        }
      ],
      "common_items": [
        {
          "name": "Elevador(es)",
          "id": 40
        }
      ]
    },
    "variants": [
      {
        "id": "v-001",
        "name": "Base unit"
      }
    ]
  },
  "media": {
    "main_image_url": "https://www.chavesnamao.com.br/673379/41518750/main.jpg",
    "thumbnail_url": "https://www.chavesnamao.com.br/673379/41518750/thumb.jpg",
    "images": [
      {
        "id": "image-0",
        "url": "https://www.chavesnamao.com.br/673379/41518750/image-0.jpg"
      },
      {
        "id": "image-1",
        "url": "https://www.chavesnamao.com.br/673379/41518750/image-1.jpg"
      }
    ],
    "videos": [
      {
        "id": "video-0",
        "url": "https://www.youtube.com/watch?t=2s&v=YcP-iu_3CCk"
      }
    ],
    "other": [
      {
        "type": "featured_image",
        "id": "featured-image",
        "url": "https://www.chavesnamao.com.br/673379/41518750/featured-image.jpg"
      }
    ],
    "image_count": 16,
    "media_count": 18
  },
  "availability": {
    "availability_status": "active",
    "status": "active",
    "show_price": true,
    "active": true,
    "highlighted": false,
    "pet_friendly": false,
    "show_condominium": true,
    "revision": false,
    "listing": {
      "status": "active",
      "featured": false,
      "resale": false
    },
    "score": 0
  },
  "contact_details": {
    "name": "ALVELAN IMOBILIÁRIA - CRECI/SP 050527-J",
    "phone": "(17) 99199-9191",
    "phones": [
      "(17) 99199-9191"
    ],
    "whatsapp": "(17) 99199-9191",
    "contact_url": "https://www.chavesnamao.com.br/imobiliaria/alvelan-imobiliaria-creci-sp-050527-j/id-673379/",
    "profiles": {
      "seller_profile_url": "https://www.chavesnamao.com.br/imobiliaria/alvelan-imobiliaria-creci-sp-050527-j/id-673379/",
      "account_profile_url": "https://www.chavesnamao.com.br/imobiliaria/alvelan-imobiliaria-creci-sp-050527-j/id-673379/"
    },
    "channels": {
      "leasing": true,
      "schedule_virtual": true,
      "schedule_irl": true,
      "message": true,
      "whatsapp": true,
      "phones": true
    }
  },
  "relationships": {
    "agent": {
      "name": "ALVELAN IMOBILIÁRIA - CRECI/SP 050527-J",
      "id": "673379",
      "profile_url": "https://www.chavesnamao.com.br/imobiliaria/alvelan-imobiliaria-creci-sp-050527-j/id-673379/",
      "license": "050527-J",
      "tier": "PJ"
    },
    "agents": [
      {
        "name": "ALVELAN IMOBILIÁRIA - CRECI/SP 050527-J",
        "id": "673379",
        "profile_url": "https://www.chavesnamao.com.br/imobiliaria/alvelan-imobiliaria-creci-sp-050527-j/id-673379/"
      }
    ],
    "agency": {
      "name": "ALVELAN IMOBILIÁRIA - CRECI/SP 050527-J",
      "license_number": "050527-J",
      "logo_url": "673379-1731416079.png",
      "tier": "PJ"
    },
    "seller": {
      "advertiser_id": "673379",
      "name": "ALVELAN IMOBILIÁRIA - CRECI/SP 050527-J",
      "profile_url": "https://www.chavesnamao.com.br/imobiliaria/alvelan-imobiliaria-creci-sp-050527-j/id-673379/",
      "license_number": "050527-J",
      "tier": "PJ",
      "logo_url": "673379-1731416079.png",
      "show_address": false,
      "created_at": "2026-02-26T03:00:00+00:00",
      "category": 0,
      "phones": {
        "cellphone": {
          "number": "(17) 99199-9191",
          "whatsapp": true
        }
      },
      "google_business": {
        "rating": 4.8,
        "totalReviews": 76
      }
    }
  },
  "metrics": {
    "score": 0,
    "rating": 4.8,
    "review_count": 76
  },
  "attributes": {
    "tags": ["destaque", "novidade"],
    "labels": ["featured"],
    "flags": {
      "active": true,
      "show_price": true,
      "is_featured": false
    },
    "source_specific": {
      "legacy_record": {
        "identity": {
          "id": "41518750"
        },
        "timestamps": {
          "published_at": "2026-04-13T10:10:06"
        }
      }
    }
  }
}

Field reference

Listing fields

Top-level

• record_type (string): Public family marker (typically property_listing).
• record_id (string): Stable identifier for row deduplication and joins.

Provenance

• source_context.source_name (string, optional): Source platform label.
• source_context.source_domain (string, optional): Source domain.
• source_context.source_url (string, optional): Search seed URL.
• source_context.canonical_url (string, optional): Canonical listing URL.
• source_context.listing_url (string, optional): Listing page URL used for extraction.
• source_context.seed_type (string, optional): Seed type.
• source_context.seed_id (string, optional): Seed identifier.
• source_context.seed_value (string, optional): Seed value.
• source_context.external_ids.id (string, optional): Listing ID from source.
• source_context.external_ids.listing_id (string, optional): Listing alias ID.

Identity and listing contract

• entity.title (string, optional): Public listing title.
• entity.headline (string, optional): Listing headline.
• entity.description (string, optional): Public description text.
• entity.category (string, optional): Category family.
• listing.listing_id (string, optional): Listing id.
• listing.listing_status (string, optional): Listing status.
• listing.transaction_type (string, optional): Sale/rent transaction type.
• listing.deal_type (string, optional): Family used by the parser.
• listing.posted_at (string, optional): Source posted timestamp.

Price and economics

• pricing.price (number | string | null, optional): Primary price.
• pricing.price_text (string, optional): Source display price.
• pricing.currency (string, optional): Price currency code.
• pricing.price_numeric (number, optional): Numeric price when normalized.
• pricing.offers[] (array[object], optional): Sale/rent offer payload.

Location

• location.address.label (string, optional): Address display label.
• location.address.street (string, optional): Street name.
• location.address.street_number (string, optional): Street number.
• location.address.neighborhood (string, optional): Neighborhood.
• location.address.city (string, optional): City.
• location.address.state_code (string, optional): State abbreviation.
• location.postal_code (string, optional): Postal code.
• location.location_accuracy (string, optional): Address granularity indicator.
• location.coordinates.latitude (number, optional): Latitude.
• location.coordinates.longitude (number, optional): Longitude.
• location.coordinates.approximate (boolean, optional): Approximate coordinates flag.

Property

• property.property_type (string, optional): Property type.
• property.property_subtype (string, optional): Property subtype.
• property.rooms (object, optional): Room counts.
• property.floor_area (number, optional): Floor area in m².
• property.area (object, optional): Area details.
• property.features.private_items[] (array[object], optional): Unit features.
• property.features.common_items[] (array[object], optional): Shared features.
• property.property_taxonomy (object, optional): Source taxonomy payload.

Availability and media

• availability.availability_status (string, optional): Availability status.
• availability.active (boolean, optional): Active flag.
• availability.score (number, optional): Listing score.
• media.main_image_url (string, optional): Main image.
• media.image_count (number, optional): Number of images.
• media.media_count (number, optional): Total media artifact count.
• media.videos[] (array[object], optional): Video entries.

Contacts and relationships

• contact_details.name (string, optional): Contact name.
• contact_details.phone (string, optional): Primary phone.
• contact_details.phones[] (array[string], optional): Phone list.
• contact_details.whatsapp (string, optional): WhatsApp number.
• contact_details.contact_url (string, optional): Contact/profile page.
• relationships.agent (object, optional): Primary linked agent.
• relationships.agency (object, optional): Linked agency.
• relationships.seller (object, optional): Seller payload.
• relationships.source_profile_urls[] (array[string], optional): Source profile and listing links.

Metrics and attributes

• metrics.score (number, optional): Listing score.
• metrics.rating (number, optional): Rating value.
• metrics.review_count (number, optional): Number of reviews.
• attributes.tags (array[string], optional): Listing tags.
• attributes.labels (array[string], optional): Labels/badges.
• attributes.flags (object, optional): Boolean-like listing flags.
• attributes.source_specific (object, optional): Full source payload preserved for completeness.
• attributes.raw_attributes (object, optional): Raw source attributes.
• attributes.neighborhood_details (object, optional): Neighborhood details when exposed.

Data guarantees & handling

• Best-effort extraction: fields may vary by region, session, listing availability, or site experiments.
• Optional fields: null-check in downstream code.
• Deduplication: prefer record_id, with source_context.external_ids.id as a secondary stable fallback.

How to Run on Apify

1. Open the Actor in Apify Console.
2. Enter your location and choose whether to collect sale or rent listings.
3. Add any optional filters you need, then set the maximum number of outputs to collect.
4. Click Start and wait for the run to finish.
5. Download results in JSON, CSV, Excel, or other supported formats.

Scheduling & Automation

Scheduling

Automated Data Collection

You can schedule recurring runs to keep your property dataset fresh without manually starting each job. This is useful for ongoing market tracking, recurring exports, and regular reporting. Scheduled runs help keep your downstream systems aligned with the latest public listings and pricing changes.

• Navigate to Schedules in Apify Console
• Create a new schedule (daily, weekly, or custom cron)
• Configure input parameters
• Enable notifications for run completion
• Add webhooks for automated processing

Integration Options

• Webhooks: Trigger downstream actions when a run completes
• Zapier: Connect to 5,000+ apps without coding
• Make (Integromat): Build multi-step automation workflows
• Google Sheets: Export results to a spreadsheet
• Slack/Discord: Receive notifications and summaries
• Email: Send automated reports via email

Performance

• Small runs (< 1,000 outputs): ~2–3 minutes
• Medium runs (1,000–5,000 outputs): ~5–15 minutes
• Large runs (5,000+ outputs): ~15–30 minutes

Execution time varies based on filters, result volume, and how much information is returned per record.

Compliance & Ethics

Responsible Data Collection

This actor collects publicly available real estate listing information from https://www.chavesnamao.com.br for legitimate business purposes. Common use cases include market analysis, listing monitoring, enrichment, and internal reporting workflows. Users are responsible for ensuring their use of collected data complies with applicable laws, regulations, and the target site's terms. This section is informational and not legal advice.

• Real estate research and market analysis
• Listing monitoring and portfolio tracking
• Data enrichment and reporting

Best Practices

• Use collected data in accordance with applicable laws, regulations, and the target site's terms
• Respect individual privacy and personal information
• Use data responsibly and avoid disruptive or excessive collection
• Do not use this actor for spamming, harassment, or other harmful purposes
• Follow relevant data protection requirements where applicable (e.g., GDPR, CCPA)

Support

If you need help, use the Issues tab or the support section on the actor page. Include the input you used with sensitive values redacted, the run ID, a short note on expected versus actual behavior, and, if helpful, a small output sample.