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 listing object per dataset item. Each record is designed for direct use in analytics pipelines, ETL jobs, warehouses, CRMs, and downstream APIs without additional post-processing.

Recommended deduplication keys:

• identity.fingerprint for stable upserts across repeated runs
• identity.id when you only need the Chaves na Mão listing id

Example listing record

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

{
  "identity": {
    "id": "41518750",
    "fingerprint": "ef99c3fe16e1dd0bad29"
  },
  "source_context": {
    "url": "https://www.chavesnamao.com.br/imovel/sala-comercial-a-venda-2-salas-sp-sao-paulo-bela-vista-126m2-RS1850000/id-41518750/",
    "source_url": "https://www.chavesnamao.com.br/imoveis/brasil/",
    "page_index": 1,
    "seed": {
      "id": "2af1977af04a",
      "type": "location",
      "value": "Sao Paulo"
    }
  },
  "timestamps": {
    "published_at": "2026-04-13T10:10:06",
    "updated_at": "2026-04-13T10:10:06"
  },
  "content": {
    "title": "Andar / meia laje Comercial com 126 m² em Venda e Aluguel, Cerqueira César - SP",
    "description": "Andar / meia laje Comercial com 126 m² em Venda e Aluguel, Cerqueira César - SP Imóvel comercial de 126 m² disponível para venda e aluguel em Cerqueira César."
  },
  "pricing": {
    "amount": 1850000,
    "currency": "BRL",
    "offers": [
      {
        "business_type": "sale",
        "amount": "R$ 1.850.000",
        "currency": "BRL",
        "monthly_condo_fee": "R$ 2.000",
        "iptu": "R$ 1.000"
      }
    ]
  },
  "availability": {
    "active": true,
    "highlighted": false,
    "pet_friendly": false,
    "show_condominium": true,
    "revision": false,
    "score": 0
  },
  "location": {
    "label": "Avenida Paulista 1765, Bela Vista, São Paulo, SP",
    "street": "Avenida Paulista",
    "street_number": "1765",
    "neighborhood": "Bela Vista",
    "city": "São Paulo",
    "state": "São Paulo",
    "state_code": "SP",
    "postal_code": "01311-200",
    "public_address": true,
    "address_complement": "ANDAR",
    "coordinates": {
      "latitude": -23.56079,
      "longitude": -46.65786
    },
    "nearby_places": {
      "bus_stops": [
        {
          "distance": 70,
          "name": "Avenida Paulista, 1754"
        }
      ],
      "hospitals": [
        {
          "distance": 310,
          "name": "Hospital 9 de Julho"
        }
      ],
      "restaurants": [
        {
          "distance": 40,
          "name": "McDonald's"
        }
      ]
    },
    "address_comp": "ANDAR"
  },
  "media": {
    "images": [
      {
        "id": "image-0",
        "url": "https://www.chavesnamao.com.br/673379/41518750/sp-sao-paulo-bela-vista-avenida-paulista-sala-comercial-a-venda-69dce1aa-00.jpg"
      },
      {
        "id": "image-1",
        "url": "https://www.chavesnamao.com.br/673379/41518750/sp-sao-paulo-bela-vista-avenida-paulista-sala-comercial-a-venda-69dce1aa-01.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/sp-sao-paulo-bela-vista-avenida-paulista-sala-comercial-a-venda-69dce1aa-00.jpg"
      }
    ],
    "image_count": 16,
    "featured_image": "673379/41518750/sp-sao-paulo-bela-vista-avenida-paulista-sala-comercial-a-venda-69dce1aa-00.jpg"
  },
  "attributes": {
    "business": "sale",
    "property_type": "conj_comercial_sala",
    "category": "commercial",
    "transaction": "sell",
    "realty_type": {
      "name": "Conj. Comercial / Sala",
      "title_name": "Conj. Comercial / Salas",
      "id": 7,
      "url": "sala-comercial",
      "prefix": "deste"
    },
    "segment": "REALTY",
    "commercial_rooms": 2,
    "show_details_characteristics": true,
    "private_items": [
      {
        "name": "Ar Condicionado",
        "id": 5
      }
    ],
    "common_items": [
      {
        "name": "Elevador(es)",
        "id": 40
      }
    ],
    "rooms": {
      "bathrooms": 2
    },
    "area": {
      "usable_area": 126,
      "total_area": 126
    }
  },
  "entities": {
    "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
        }
      }
    }
  },
  "contact": {
    "phones": [
      "(17) 99199-9191"
    ],
    "whatsapp": "(17) 99199-9191",
    "channels": {
      "leasing": true,
      "schedule_virtual": true,
      "schedule_irl": true,
      "message": true,
      "whatsapp": true,
      "phones": true
    }
  }
}

Field reference

Listing fields

• identity.id (string, optional): Source listing ID.
• identity.external_id (string, optional): Provider-facing external reference.
• identity.legacy_id (string, optional): Legacy source reference when present.
• identity.source_id (string, optional): Source system identifier.
• identity.provider_id (string, optional): Provider or advertiser reference ID.
• identity.fingerprint (string, optional): Record fingerprint for source-level identity tracking.
• source_context.url (string, optional): Listing page URL used for the record.
• source_context.source_url (string, optional): Search page URL where the listing was discovered.
• source_context.page_index (number, optional): Search results page index.
• source_context.seed.id (string, optional): Identifier for the originating search seed.
• source_context.seed.type (string, optional): Seed category, such as location or url.
• source_context.seed.value (string, optional): Original seed value.
• timestamps.published_at (string, optional): Publication timestamp in ISO 8601 format.
• timestamps.created_at (string, optional): Original creation timestamp in ISO 8601 format.
• timestamps.updated_at (string, optional): Last update timestamp in ISO 8601 format.
• content.title (string, optional): Listing title.
• content.description (string, optional): Listing description text.
• pricing.amount (number, optional): Primary displayed price.
• pricing.currency (string, optional): Currency code for the primary price.
• pricing.offers[] (array[object], optional): Offer variants associated with the listing.
• pricing.offers[].business_type (string, optional): Offer type, such as sale or rent.
• pricing.offers[].amount (string | number, optional): Offer amount as displayed or normalized by the actor.
• pricing.offers[].currency (string, optional): Offer currency code.
• pricing.offers[].monthly_condo_fee (string | number, optional): Monthly condo fee when available.
• pricing.offers[].iptu (string | number, optional): IPTU value when available.
• pricing.offers[].yearly_iptu (string | number, optional): Yearly IPTU value when available.
• pricing.offers[].rental_terms.monthly_total (string | number, optional): Rental total when exposed.
• availability.status (string, optional): Listing availability status.
• availability.show_price (boolean, optional): Whether price is publicly shown.
• availability.accept_exchange (boolean, optional): Whether exchanges are accepted.
• availability.resale (boolean, optional): Whether the listing is marked as resale.
• availability.non_activation_reason (string, optional): Reason a listing is not active, when present.
• availability.active (boolean, optional): Whether the listing is active.
• availability.highlighted (boolean, optional): Whether the listing is highlighted on the platform.
• availability.pet_friendly (boolean, optional): Pet-friendly flag when exposed.
• availability.show_condominium (boolean, optional): Whether condominium details are exposed.
• availability.revision (boolean, optional): Revision flag when present.
• availability.score (number, optional): Listing score when present.
• location.label (string, optional): Short location label.
• location.full_address (string, optional): Full address string when available.
• location.street (string, optional): Street name.
• location.street_number (string, optional): Street number.
• location.neighborhood (string, optional): Neighborhood name.
• location.city (string, optional): City name.
• location.state (string, optional): Full state name.
• location.state_code (string, optional): State code.
• location.postal_code (string, optional): Postal code.
• location.public_address (boolean, optional): Whether the address is public.
• location.address_complement (string, optional): Address complement when available.
• location.coordinates.latitude (number, optional): Latitude.
• location.coordinates.longitude (number, optional): Longitude.
• location.coordinates.approximate (boolean, optional): Whether the coordinates are approximate.
• location.coordinates.radius_meters (number, optional): Approximate radius in meters when exposed.
• location.coordinates.source (string, optional): Coordinate source label.
• location.nearby_places (object, optional): Nearby places grouped by category such as bus stops, hospitals, parks, schools, gyms, restaurants, supermarkets, and pharmacies.
• location.geocoding.address_type (string, optional): Address granularity classification.
• media.images[] (array[object], optional): Image assets associated with the listing.
• media.videos[] (array[object], optional): Video assets associated with the listing.
• media.other[] (array[object], optional): Additional media items.
• media.image_count (number, optional): Reported image count.
• media.featured_image (string, optional): Featured image path or URL.
• media.tours[] (array[object], optional): Tour or 360 links when available.
• attributes.business (string, optional): Business type, such as sale or rent.
• attributes.contract_type (string, optional): Contract classification.
• attributes.listing_type (string, optional): Listing class.
• attributes.property_type (string, optional): High-level property classification.
• attributes.publication_type (string, optional): Publication tier or listing class.
• attributes.construction_status (string, optional): Construction status.
• attributes.display_address_type (string, optional): Address display mode.
• attributes.portal (string, optional): Primary portal name.
• attributes.portals[] (array[string], optional): Related portal names.
• attributes.unit_types[] (array[string], optional): Unit type labels.
• attributes.unit_sub_types[] (array[string], optional): Unit subtype labels.
• attributes.usage_types[] (array[string], optional): Usage type labels.
• attributes.amenities[] (array[string], optional): Amenity labels.
• attributes.badges[] (array[string], optional): Listing badges or stamps.
• attributes.condominium_name (string, optional): Condominium name when available.
• attributes.category (string, optional): Residential or commercial category.
• attributes.transaction (string, optional): Transaction type, normalized such as sell.
• attributes.realty_type (object, optional): Chaves na Mão realty type object.
• attributes.segment (string, optional): Source segment label.
• attributes.commercial_rooms (number, optional): Commercial room count when exposed.
• attributes.private_items[] (array[object], optional): Private-unit features.
• attributes.common_items[] (array[object], optional): Common-area features.
• attributes.rooms (object, optional): Room counts such as bedrooms, bathrooms, suites, and parking spaces.
• attributes.area (object, optional): Area values such as usable and total square meters.
• attributes.variants[] (array[object], optional): Child units or listing variants when available.
• entities.seller.account_id (string, optional): Seller account identifier.
• entities.seller.advertiser_id (string, optional): Advertiser identifier.
• entities.seller.name (string, optional): Seller or agency name.
• entities.seller.profile_url (string, optional): Seller profile URL.
• entities.seller.license_number (string, optional): License or registration number.
• entities.seller.tier (string, optional): Seller tier or badge level.
• entities.seller.logo_url (string, optional): Seller logo URL.
• entities.seller.verified (boolean, optional): Whether the seller is verified.
• entities.seller.show_address (boolean, optional): Whether the seller address is displayed.
• entities.seller.created_at (string, optional): Seller profile creation timestamp in ISO 8601 format.
• entities.seller.trust_score (number, optional): Seller trust score when available.
• entities.seller.total_count_by_filter (number, optional): Seller listing count for the current filter when exposed.
• entities.seller.total_count_by_advertiser (number, optional): Seller listing count across the advertiser profile when exposed.
• entities.seller.category (number, optional): Seller category code.
• entities.seller.address (object, optional): Seller address object.
• entities.seller.phones (object | array, optional): Seller phone object(s).
• entities.seller.google_business (object, optional): Google Business details when available.
• entities.developers[] (array[object], optional): Developer entities for new-project records when present.
• contact.phones[] (array[string], optional): Public phone numbers.
• contact.whatsapp (string, optional): Public WhatsApp number.
• contact.channels (object, optional): Public lead and communication channels.

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: recommend identity.fingerprint, with identity.id as a simpler 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.