# VivaReal Scraper| $1.5 / 1k | Fast & Reliable (`fatihtahta/vivareal-scraper`) Actor Extract structured Brazil property listings from VivaReal Imoveis with pricing, locations, seller details, media assets, and contact data. Built for enterprise-grade Brazil real estate intelligence, listing monitoring, lead enrichment and automated analytics pipelines. - **URL**: https://apify.com/fatihtahta/vivareal-scraper.md - **Developed by:** [Fatih Tahta](https://apify.com/fatihtahta) (community) - **Categories:** Real estate, Automation, Developer tools - **Stats:** 2 total users, 1 monthly users, 100.0% runs succeeded, 1 bookmarks - **User rating**: No ratings yet ## Pricing from $1.50 / 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/platform/actors/running/actors-in-store#pay-per-event ## What's an Apify Actor? Actors are a software tools running on the Apify platform, for all kinds of web data extraction and automation use cases. 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. In JavaScript/TypeScript projects, use official [JavaScript/TypeScript client](https://docs.apify.com/api/client/js.md): ```bash npm install apify-client ``` In Python projects, use official [Python client library](https://docs.apify.com/api/client/python.md): ```bash pip install apify-client ``` In shell scripts, use [Apify CLI](https://docs.apify.com/cli/docs.md): ````bash # MacOS / Linux curl -fsSL https://apify.com/install-cli.sh | bash # Windows irm https://apify.com/install-cli.ps1 | iex ```bash In AI frameworks, you might use the [Apify MCP server](https://docs.apify.com/platform/integrations/mcp.md). If your project is in a different language, use 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 ## VivaReal Imoveis Scraper **Slug:** `fatihtahta/vivareal-imoveis-scraper` ### Overview VivaReal Imoveis Scraper turns VivaReal property searches and listing URLs into structured, production-ready real estate data. It returns normalized records with pricing, location, media, property attributes, seller details, and public contact fields so teams can move from raw listings to analysis, enrichment, reporting, and automation without manual cleanup. Use it when you need consistent Brazilian property data for market intelligence, listing monitoring, CRM workflows, recurring exports, or operational dashboards. The output is designed to be easy to consume in Apify Console, the Apify API, the Apify CLI, and automation tools such as Zapier, Make, and n8n. ### What You Get - **Structured property records:** Clean JSON items ready for analytics, monitoring, and downstream processing. - **Normalized key fields:** Pricing, location, media, property characteristics, seller metadata, and public contact data in one record. - **Flexible input options:** Start from area-based searches, direct listing URLs, or a combination of both. - **Dataset-ready output:** Results land in an Apify dataset for export to JSON, CSV, Excel, and connected workflows. - **Automation-friendly runs:** Suitable for one-off jobs, recurring schedules, API-driven runs, and no-code integrations. ### Best For - **Market intelligence:** Track supply, pricing bands, neighborhood activity, and property mix across Brazilian markets. - **Listing monitoring:** Watch active inventory, pricing updates, and new opportunities over time. - **Research pipelines:** Feed structured real estate records into internal analysis, warehousing, or enrichment workflows. - **CRM enrichment:** Add seller, agency, and property context to lead and account workflows. - **Internal reporting:** Build recurring exports for spreadsheets, BI tools, and operational dashboards. ### Quick Start Paste a simple input like this into Apify Console to start a focused run: ```json { "location": "Rio de Janeiro", "deal_type": "sale", "limit": 100 } ```` Typical run flow: 1. Open the actor in Apify Console. 2. Paste your JSON input and adjust any filters you want. 3. Start the run. 4. Open the run's dataset after completion. 5. Export the results or connect them to your next workflow. ### Input Parameters Provide either `location`, `startUrls`, or both. Add filters to narrow the dataset to the market slice you want. | Parameter | Type | Description | Default | | --- | --- | --- | --- | | `startUrls` | `array[string\|object]` | One or more VivaReal listing or search URLs. Apify `Request`-style objects are also accepted. | `[]` | | `location` | `string` | A city, neighborhood, district, avenue, or street in Brazil, such as `Rio de Janeiro` or `Pinheiros, Sao Paulo`. | – | | `deal_type` | `string` | Whether to collect sale or rental listings. Allowed values: `sale`, `rent`. | `sale` | | `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`, `store`, `office`, `commercial_house`, `hotel`, `corporate_floor`, `building`, `commercial_land`, `storage`, `garage`. | – | | `amenities` | `array[string]` | One or more amenities to include. Allowed values: `pets_allowed`, `heating`, `air_conditioning`, `service_area`, `builtin_wardrobe`, `bedroom_wardrobe`, `kitchen_cabinets`, `bathroom_cabinets`, `blindex_box`, `gas_shower`, `closet`, `internet_access`, `american_kitchen`, `gourmet_kitchen`, `large_kitchen`, `home_office`, `intercom`, `large_window`, `furnished`, `backyard`, `cable_tv`, `balcony`, `gourmet_balcony`, `natural_ventilation`, `bathtub`, `panoramic_view`, `freezer`, `cooker`, `deposit`, `private_pool`. | – | | `min_bedroom` | `string` | Minimum bedroom count. Allowed values: `1`, `2`, `3`, `4` for 1+, 2+, 3+, or 4+ bedrooms. | – | | `min_bathroom` | `string` | Minimum bathroom count. Allowed values: `1`, `2`, `3`, `4` for 1+, 2+, 3+, or 4+ bathrooms. | – | | `min_parking` | `string` | Minimum parking space count. Allowed values: `1`, `2`, `3`, `4` for 1+, 2+, 3+, or 4+ spaces. | – | | `min_price` | `integer` | Minimum listing price. Use whole numbers such as `400000`. | – | | `max_price` | `integer` | Maximum listing price. Use whole numbers such as `3000000`. | – | | `below_market_price` | `boolean` | When `true`, keeps only listings marked by VivaReal/DataZAP 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 public transit. | `false` | | `maximize_coverage` | `boolean` | When `true`, prioritizes broader retrieval on larger searches when you want stronger dataset completeness. | `false` | | `limit` | `integer` | Maximum number of listings to save for each search seed. Leave empty to collect all available results. | – | ### More Example Inputs #### Scenario: Broad city sale search ```json { "location": "Rio de Janeiro", "deal_type": "sale", "property_type": ["apartment", "house"], "min_price": 250000, "max_price": 1200000, "limit": 250 } ``` #### Scenario: Neighborhood search with size and amenity filters ```json { "location": "Vila Mariana, Sao Paulo", "deal_type": "sale", "property_type": ["apartment"], "min_sqm": 70, "max_sqm": 180, "amenities": ["balcony", "air_conditioning"], "limit": 200 } ``` #### Scenario: Rental search with transit filter ```json { "location": "Pinheiros, Sao Paulo", "deal_type": "rent", "property_type": ["apartment", "studio"], "min_bedroom": "1", "near_transit": true, "max_price": 6000, "limit": 150 } ``` #### Scenario: Direct listing URLs ```json { "startUrls": [ "https://www.vivareal.com.br/imovel/apartamento-3-quartos-iraja-rio-de-janeiro-com-garagem-98m2-venda-RS295000-id-2880363892/" ] } ``` ### Output #### Output destination The actor writes results to an Apify dataset as JSON records. Each dataset item is a normalized listing record without an extra top-level wrapper like `type`, `id`, or `url`. #### Record structure Each output item can include these top-level sections when data is available: - `identity` - `source_context` - `timestamps` - `content` - `pricing` - `availability` - `location` - `media` - `attributes` - `entities` - `contact` Recommended deduplication keys: 1. `identity.id` 2. `identity.fingerprint` 3. `source_context.url` #### Output Highlights - `identity`: Useful for deduplication, change tracking, record matching, and historical comparisons. - `pricing`: Supports sale and rental analysis, price monitoring, and portfolio-level reporting. - `location`: Makes it easy to group listings by city, neighborhood, state, and coordinates for mapping or territory analysis. - `attributes`: Helps segment inventory by property type, area, room counts, amenities, and listing characteristics. - `entities`: Adds seller and agency context for enrichment, account mapping, and market participation analysis. - `contact`: Exposes public contact fields that can support research and lead qualification workflows when present. #### Example output This is an example VivaReal dataset item aligned with the actor's output format: ```json { "identity": { "id": "2880363892", "external_id": "PAAP31641", "source_id": "c4b61b04-d96b-363f-9774-635c34081d26", "provider_id": "84945", "fingerprint": "47c70add902f38bd61b5" }, "source_context": { "url": "https://www.vivareal.com.br/imovel/apartamento-3-quartos-iraja-rio-de-janeiro-com-garagem-98m2-venda-RS295000-id-2880363892/", "source_url": "https://www.vivareal.com.br/", "page_index": 1, "seed": { "id": "02231b015915", "type": "location", "value": "rio de janerio" } }, "timestamps": { "published_at": "2026-04-15T03:04:46.048000+00:00", "created_at": "2026-04-12T02:51:25.013000+00:00", "updated_at": "2026-04-15T03:04:46.048000+00:00" }, "content": { "title": "Apartamento 3 quartos, dependência completa, 2 vagas em Irajá", "description": "h6 Excelente apartamento no bairro de Irajá, amplo, composto de salão com piso parquet paulista, tres quartos ambos em parquet paulista, sendo um com armário planejado e suite com box blindex, banheiro social com box blindex, ampla cozinha com armarios planejados, area de serviço separada, dependencia completa de empregada, 2 vagas de garagem na escritura. , planta generosa. /h6 h6 Proxímo de todo comércio, escolas, condução e mercados. /h6 h6 Ligue e agende sua visita com um de nossos corretores. /h6 -Cod:PAAP31641 -Rev.14Abr" }, "pricing": { "amount": 295000, "currency": "BRL", "offers": [ { "business_type": "sale", "amount": 295000, "currency": "BRL", "monthly_condo_fee": 627, "yearly_iptu": 540 } ] }, "availability": { "status": "active", "show_price": true, "accept_exchange": false, "resale": false, "non_activation_reason": "none" }, "location": { "label": "Irajá", "street": "Rua Honório de Almeida", "street_number": "69", "neighborhood": "Irajá", "city": "Rio de Janeiro", "state_code": "RJ", "coordinates": { "latitude": -22.836969, "longitude": -43.323003, "source": "GOOGLE" }, "geocoding": { "address_type": "all" } }, "media": { "images": [ { "id": "5e442a0a4aedf53f0329a2942a053fc1", "url": "https://resizedimgs.vivareal.com/img/vr-listing/5e442a0a4aedf53f0329a2942a053fc1/{description}.webp?action=%7Baction%7D&dimension=%7Bwidth%7Dx%7Bheight%7D" }, { "id": "bd9d437ca32121a62b2b18e37a573667", "url": "https://resizedimgs.vivareal.com/img/vr-listing/bd9d437ca32121a62b2b18e37a573667/{description}.webp?action=%7Baction%7D&dimension=%7Bwidth%7Dx%7Bheight%7D" } ], "videos": [ { "id": "d733e4a4adf88af4a20dd64dd1517b0f", "url": "https://www.youtube.com/watch?v=bkxUPamY1eM" } ] }, "attributes": { "business": "sale", "contract_type": "real_estate", "listing_type": "used", "property_type": "unit", "publication_type": "premium", "construction_status": "none", "display_address_type": "all", "portal": "grupozap", "portals": [ "olx", "vivareal", "zap" ], "unit_types": [ "apartment" ], "usage_types": [ "residential" ], "amenities": [ "builtin_wardrobe", "intercom", "service_bathroom", "aluminum_window", "large_window", "blindex_box", "kitchen_cabinets", "service_area", "pets_allowed" ], "badges": [ "DATAZAP_APPROVED_SALE" ], "buildings": 0, "floors": [ 3 ], "units_on_the_floor": 0, "unit_floor": 2, "rooms": { "bedrooms": 3, "bedroom_options": [ 3 ], "bathrooms": 3, "bathroom_options": [ 3 ], "suites": 1, "suite_options": [ 1 ], "parking_spaces": 2, "parking_space_options": [ 2 ] }, "area": { "usable_area": 98, "usable_area_options": [ 98 ], "total_area": 98, "total_area_options": [ 98 ] } }, "entities": { "seller": { "account_id": "832396ba-4c6d-4966-2a56-1af9a9d4db3c", "advertiser_id": "832396ba-4c6d-4966-2a56-1af9a9d4db3c", "name": "Patrimônio Rio Imobiliária", "profile_url": "https://www.vivareal.com.br/imobiliaria/38595/", "license_number": "06232-J-RJ", "tier": "diamond", "logo_url": "https://resizedimgs.vivareal.com/img/vr-listing/b848c2dc156eec51c85ec52c3ceca91b/{description}.webp?action=%7Baction%7D&dimension=%7Bwidth%7Dx%7Bheight%7D", "show_address": true, "created_at": "2018-03-27T14:32:59+00:00", "legacy_vivareal_id": 38595, "legacy_zap_id": 1737804 } }, "contact": { "phones": [ "21995819223" ], "whatsapp": "21995819223" } } ``` ### Field Reference #### `identity` - `identity.id` *(string, optional)*: VivaReal listing ID. - `identity.external_id` *(string, optional)*: Provider-facing listing reference. - `identity.legacy_id` *(string, optional)*: Legacy listing identifier when present. - `identity.source_id` *(string, optional)*: Source-system identifier. - `identity.provider_id` *(string, optional)*: Provider or advertiser reference ID. - `identity.fingerprint` *(string, optional)*: Stable fingerprint generated from listing identity data. #### `source_context` - `source_context.url` *(string, optional)*: Canonical listing URL used for the record. - `source_context.source_url` *(string, optional)*: Search or seed 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` - `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` - `content.title` *(string, optional)*: Listing title. - `content.description` *(string, optional)*: Listing description text. #### `pricing` - `pricing.amount` *(number, optional)*: Primary displayed price. - `pricing.currency` *(string, optional)*: Currency code for the main 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` *(number, optional)*: Offer amount. - `pricing.offers[].currency` *(string, optional)*: Offer currency code. - `pricing.offers[].monthly_condo_fee` *(number, optional)*: Monthly condo fee when available. - `pricing.offers[].yearly_iptu` *(number, optional)*: Yearly IPTU tax when available. - `pricing.offers[].iptu` *(number, optional)*: IPTU amount when reported in an alternate format. - `pricing.offers[].iptu_period` *(string, optional)*: IPTU recurrence period when available. - `pricing.offers[].rental_period` *(string, optional)*: Rental billing period when present. - `pricing.offers[].monthly_rental_total_price` *(number, optional)*: Total monthly rent cost when available. - `pricing.offers[].warranties[]` *(array\[string], optional)*: Accepted rental guarantees. #### `availability` - `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 inactive, when present. #### `location` - `location.label` *(string, optional)*: Short location label. - `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_code` *(string, optional)*: State code. - `location.coordinates.latitude` *(number, optional)*: Latitude. - `location.coordinates.longitude` *(number, optional)*: Longitude. - `location.coordinates.source` *(string, optional)*: Coordinate source label. - `location.geocoding.address_type` *(string, optional)*: Address granularity classification. #### `media` - `media.images[]` *(array\[object], optional)*: Image assets. - `media.images[].id` *(string, optional)*: Image identifier. - `media.images[].url` *(string, optional)*: Image URL template or asset URL. - `media.videos[]` *(array\[object], optional)*: Video assets. - `media.videos[].id` *(string, optional)*: Video identifier. - `media.videos[].url` *(string, optional)*: Video URL. - `media.other[]` *(array\[object], optional)*: Additional media items when available. #### `attributes` - `attributes.business` *(string, optional)*: Business type such as `sale` or `rent`. - `attributes.contract_type` *(string, optional)*: Contract classification. - `attributes.listing_type` *(string, optional)*: Listing condition or class. - `attributes.property_type` *(string, optional)*: High-level property classification. - `attributes.publication_type` *(string, optional)*: Publication tier. - `attributes.construction_status` *(string, optional)*: Construction status. - `attributes.expansion_type` *(string, optional)*: Expansion or promotion type when available. - `attributes.display_address_type` *(string, optional)*: Address display mode. - `attributes.portal` *(string, optional)*: Primary portal label. - `attributes.portals[]` *(array\[string], optional)*: Related portal labels. - `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 stamps or badges such as below-market markers. - `attributes.condominium_name` *(string, optional)*: Condominium name when present. - `attributes.enhanced_development` *(boolean, optional)*: Enhanced development flag. - `attributes.listings_count` *(number, optional)*: Related listing count when provided. - `attributes.buildings` *(number, optional)*: Building count. - `attributes.floors[]` *(array\[number], optional)*: Floor options or floor values. - `attributes.units_on_the_floor` *(number, optional)*: Units on the floor. - `attributes.unit_floor` *(number, optional)*: Unit floor. - `attributes.capacity_limit` *(array|object|number|string, optional)*: Capacity-related value when present in source data. - `attributes.modality` *(array|object|string, optional)*: Listing modality when available. - `attributes.price_suggestion` *(array|object, optional)*: Price suggestion block when available. - `attributes.rooms.bedrooms` *(number, optional)*: Bedroom count. - `attributes.rooms.bedroom_options[]` *(array\[number], optional)*: Available bedroom count options. - `attributes.rooms.bathrooms` *(number, optional)*: Bathroom count. - `attributes.rooms.bathroom_options[]` *(array\[number], optional)*: Available bathroom count options. - `attributes.rooms.suites` *(number, optional)*: Suite count. - `attributes.rooms.suite_options[]` *(array\[number], optional)*: Available suite count options. - `attributes.rooms.parking_spaces` *(number, optional)*: Parking space count. - `attributes.rooms.parking_space_options[]` *(array\[number], optional)*: Available parking options. - `attributes.area.usable_area` *(number, optional)*: Usable area in square meters. - `attributes.area.usable_area_options[]` *(array\[number], optional)*: Available usable area values. - `attributes.area.total_area` *(number, optional)*: Total area in square meters. - `attributes.area.total_area_options[]` *(array\[number], optional)*: Available total area values. - `attributes.variants[]` *(array\[object], optional)*: Child listing or unit variants when provided by the source. #### `entities` - `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)*: Verification flag when available. - `entities.seller.show_address` *(boolean, optional)*: Whether seller address is displayed. - `entities.seller.created_at` *(string, optional)*: Seller profile creation timestamp in ISO 8601 format. - `entities.seller.legacy_vivareal_id` *(number, optional)*: Legacy VivaReal account identifier. - `entities.seller.legacy_zap_id` *(number, optional)*: Legacy ZAP account identifier. - `entities.seller.trust_score` *(number, optional)*: Seller trust score when provided. - `entities.seller.total_count_by_filter` *(number, optional)*: Seller count for the current filter. - `entities.seller.total_count_by_advertiser` *(number, optional)*: Total seller inventory count. - `entities.developers[]` *(array\[object], optional)*: Developer entities when present. #### `contact` - `contact.phones[]` *(array\[string], optional)*: Public phone numbers. - `contact.whatsapp` *(string, optional)*: Public WhatsApp number. ### Data Notes - The scraper returns the listing data publicly available at run time. - Output fields are normalized for downstream analysis and automation. - Some fields appear only when they are present on the listing. - Dataset items are ready for exports, dashboards, spreadsheets, CRMs, and custom data pipelines. - Cross-portal labels such as `olx`, `vivareal`, or `zap` can appear in portal-related fields when they are present in the listing data. ### How Teams Commonly Use The Output - **Trend analysis:** Compare pricing, property mix, and active inventory across cities, neighborhoods, or custom filter sets. - **Pricing dashboards:** Feed BI tools or spreadsheets with normalized listing prices, condo fees, and location context. - **Lead qualification:** Review seller, agency, and public contact data alongside listing characteristics. - **Location-based reporting:** Build neighborhood or city-level views for research, coverage planning, or sales ops. - **Content and marketplace support:** Populate internal collections, market pages, and property catalog workflows with structured records. ### How to Run #### Apify Console 1. Open the actor in Apify Console. 2. Enter a `location`, `startUrls`, or both. 3. Add any optional filters you need and set `limit` if you want to cap results per seed. 4. Click **Start** and wait for the run to finish. 5. Export the dataset in JSON, CSV, Excel, or another supported format. #### Apify API Use the Apify API or Apify client libraries when you want to trigger runs programmatically from your application or backend workflow. Send the same JSON input you use in Console, wait for the run if needed, then read the output from the run's default dataset. #### Apify CLI Use the Apify CLI when you want to launch runs from scripts, terminals, CI jobs, or operator workflows. The CLI uses the same actor input structure as Apify Console, which makes it easy to move from manual runs to scripted execution. #### Automation Tools This actor fits well into no-code and low-code workflows: - **Zapier:** Send run results into spreadsheets, alerts, or downstream business apps. - **Make:** Chain the dataset output into multi-step automation scenarios. - **n8n:** Trigger runs, process dataset items, and route the output to internal systems. - **Webhooks:** Start follow-up jobs when a run finishes. ### Scheduling and Automation You can schedule recurring runs to keep your dataset fresh without starting each job manually. - Create a schedule in Apify Console. - Configure the actor input for the target location, URLs, and filters. - Run it daily, weekly, or on a custom cron. - Add webhooks or automation steps for downstream processing. #### Integration options - **Apify API:** Start runs from applications, backends, and internal tools. - **Apify CLI:** Trigger runs from shell scripts and operational workflows. - **Webhooks:** Trigger downstream jobs when a run completes. - **Zapier:** Send output to spreadsheets, CRMs, and no-code flows. - **Make:** Build multi-step automation workflows. - **n8n:** Connect actor runs to custom automation and data routing pipelines. - **Google Sheets:** Export and review listing data in a spreadsheet. - **Slack or email:** Send alerts and summaries after runs. ### Performance - **Small runs (< 1,000 outputs):** ~2 to 3 minutes - **Medium runs (1,000 to 5,000 outputs):** ~5 to 15 minutes - **Large runs (5,000+ outputs):** ~15 to 30 minutes Execution time varies with filters, source response times, and how much data is returned per listing. ### Compliance and Responsible Use This actor collects publicly available real estate listing information from **https://www.vivareal.com.br/** for legitimate business purposes such as 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 site terms. This section is informational and not legal advice. - Use collected data in accordance with applicable laws and site terms. - Respect privacy and personal information. - Avoid disruptive or excessive collection. - Do not use the actor for spam, harassment, or harmful activity. - Follow relevant data protection requirements where applicable. ### FAQ #### Can I search by area instead of direct listing URLs? Yes. Use the `location` input to run area-based searches such as cities, neighborhoods, districts, avenues, or streets in Brazil. #### Can I use direct listing URLs? Yes. Pass one or more listing URLs in `startUrls` when you want the run to start from specific properties or saved search pages. #### Can I export the data into other tools? Yes. The actor writes output to an Apify dataset that can be exported in formats such as JSON, CSV, and Excel, or consumed in your own applications and automations. #### Can I run it on a schedule? Yes. Apify schedules let you run the actor daily, weekly, or on a custom cron so your dataset stays current for recurring workflows. #### Is the output suitable for analytics and enrichment? Yes. The output is normalized for downstream analysis, reporting, enrichment, monitoring, and operational workflows. #### Can I connect it to Zapier, Make, or n8n? Yes. The actor works well with webhook-driven and dataset-driven automations, including Zapier, Make, and n8n workflows. #### What should I include if I need support? Share the input you used with sensitive values removed, the run ID, what you expected, what happened instead, and a small sample of the output if it helps explain the issue. ### 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. # Actor input Schema ## `deal_type` (type: `string`): Choose whether to collect sale listings or rent listings for this run. ## `location` (type: `string`): Enter one place name or address-style query. Examples: Rio de Janeiro, Estrada de Pau-Ferro, Borrazopolis, Borralho. ## `property_type` (type: `array`): Leave this blank to search all property types for the chosen location. Select one or more options to narrow the results. ## `amenities` (type: `array`): Leave this blank to search all listings regardless of amenities. Select one or more options to narrow the results. ## `min_bedroom` (type: `string`): Choose the minimum number of bedrooms to include. Example: `2+` keeps listings with 2, 3, or 4 bedrooms. ## `min_bathroom` (type: `string`): Choose the minimum number of bathrooms to include. Example: `2+` keeps listings with 2, 3, or 4 bathrooms. ## `min_parking` (type: `string`): Choose the minimum number of parking spaces to include. Example: `1+` keeps listings with 1, 2, 3, or 4 spaces. ## `min_price` (type: `integer`): Enter the minimum listing price. Example: `400000` keeps properties priced at 400,000 and above. ## `max_price` (type: `integer`): Enter the maximum listing price. Example: `3000000` keeps properties priced at 3,000,000 and below. ## `min_sqm` (type: `integer`): Enter the minimum usable area in square meters. Example: `35` keeps listings with 35 sqm or more. ## `max_sqm` (type: `integer`): Enter the maximum usable area in square meters. Example: `100` keeps listings with 100 sqm or less. ## `near_transit` (type: `boolean`): Enable this to filter for properties that VivaReal tags as close to metro, train, or other transit access. ## `below_market_price` (type: `boolean`): Enable this to keep only listings with VivaReal's below-market pricing badge. ## `limit` (type: `integer`): Set how many listings to save for this run. Leave it empty to collect everything available for the selected search. ## `maximize_coverage` (type: `boolean`): Use this option to improve coverage for searches that return very large numbers of listings. It is recommended when you want the most complete results possible for your selected criteria. ## Actor input object example ```json { "deal_type": "sale", "location": "Sao Paulo", "near_transit": false, "below_market_price": false, "limit": 100, "maximize_coverage": true } ``` # 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 '' with your token const client = new ApifyClient({ token: '', }); // Prepare Actor input const input = { "location": "Sao Paulo", "limit": 100 }; // Run the Actor and wait for it to finish const run = await client.actor("fatihtahta/vivareal-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 '' with your token. client = ApifyClient("") # Prepare the Actor input run_input = { "location": "Sao Paulo", "limit": 100, } # Run the Actor and wait for it to finish run = client.actor("fatihtahta/vivareal-scraper").call(run_input=run_input) # Fetch and print Actor results from the run's dataset (if there are any) print("💾 Check your data here: https://console.apify.com/storage/datasets/" + run["defaultDatasetId"]) for item in client.dataset(run["defaultDatasetId"]).iterate_items(): print(item) # 📚 Want to learn more 📖? Go to → https://docs.apify.com/api/client/python/docs/quick-start ``` ## CLI example ```bash echo '{ "location": "Sao Paulo", "limit": 100 }' | apify call fatihtahta/vivareal-scraper --silent --output-dataset ``` ## MCP server setup ```json { "mcpServers": { "apify": { "command": "npx", "args": [ "mcp-remote", "https://mcp.apify.com/?tools=fatihtahta/vivareal-scraper", "--header", "Authorization: Bearer " ] } } } ``` ## OpenAPI specification ```json { "openapi": "3.0.1", "info": { "title": "VivaReal Scraper| $1.5 / 1k | Fast & Reliable", "description": "Extract structured Brazil property listings from VivaReal Imoveis with pricing, locations, seller details, media assets, and contact data. Built for enterprise-grade Brazil real estate intelligence, listing monitoring, lead enrichment and automated analytics pipelines.", "version": "1.0", "x-build-id": "HVDKvwcxbv5vAqrKi" }, "servers": [ { "url": "https://api.apify.com/v2" } ], "paths": { "/acts/fatihtahta~vivareal-scraper/run-sync-get-dataset-items": { "post": { "operationId": "run-sync-get-dataset-items-fatihtahta-vivareal-scraper", "x-openai-isConsequential": false, "summary": "Executes an Actor, waits for its completion, and returns Actor's dataset items in response.", "tags": [ "Run Actor" ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/inputSchema" } } } }, "parameters": [ { "name": "token", "in": "query", "required": true, "schema": { "type": "string" }, "description": "Enter your Apify token here" } ], "responses": { "200": { "description": "OK" } } } }, "/acts/fatihtahta~vivareal-scraper/runs": { "post": { "operationId": "runs-sync-fatihtahta-vivareal-scraper", "x-openai-isConsequential": false, "summary": "Executes an Actor and returns information about the initiated run in response.", "tags": [ "Run Actor" ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/inputSchema" } } } }, "parameters": [ { "name": "token", "in": "query", "required": true, "schema": { "type": "string" }, "description": "Enter your Apify token here" } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/runsResponseSchema" } } } } } } }, "/acts/fatihtahta~vivareal-scraper/run-sync": { "post": { "operationId": "run-sync-fatihtahta-vivareal-scraper", "x-openai-isConsequential": false, "summary": "Executes an Actor, waits for completion, and returns the OUTPUT from Key-value store in response.", "tags": [ "Run Actor" ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/inputSchema" } } } }, "parameters": [ { "name": "token", "in": "query", "required": true, "schema": { "type": "string" }, "description": "Enter your Apify token here" } ], "responses": { "200": { "description": "OK" } } } } }, "components": { "schemas": { "inputSchema": { "type": "object", "properties": { "deal_type": { "title": "Choose a deal type", "enum": [ "sale", "rent" ], "type": "string", "description": "Choose whether to collect sale listings or rent listings for this run.", "default": "sale" }, "location": { "title": "Enter the location you want to search", "type": "string", "description": "Enter one place name or address-style query. Examples: Rio de Janeiro, Estrada de Pau-Ferro, Borrazopolis, Borralho." }, "property_type": { "title": "Which property types should be included?", "uniqueItems": true, "type": "array", "description": "Leave this blank to search all property types for the chosen location. Select one or more options to narrow the results.", "items": { "type": "string", "enum": [ "apartment", "studio", "kitnet", "house", "gated_house", "villa_house", "penthouse", "flat", "loft", "residential_land", "townhouse", "farm", "store", "office", "commercial_house", "hotel", "corporate_floor", "building", "commercial_land", "storage", "garage" ], "enumTitles": [ "🏠 Apartamento | Apartment", "🏠 Studio | Studio", "🏠 Kitnet | Studio apartment", "🏠 Casa | House", "🏠 Casa de Condomínio | Gated community house", "🏠 Casa de Vila | Villa house", "🏠 Cobertura | Penthouse", "🏠 Flat | Serviced apartment", "🏠 Loft | Loft", "🏠 Terreno / Lote / Condomínio | Land / Plot / Condominium lot", "🏠 Sobrados | Townhouse", "🏠 Fazenda / Sítio / Chácara | Farm / Country house", "🏢 Loja / Salão / Ponto Comercial | Store / Shop / Commercial space", "🏢 Conjunto Comercial / Sala | Commercial office / Room", "🏢 Casa Comercial | Commercial house", "🏢 Hotel / Motel / Pousada | Hotel / Motel / Guesthouse", "🏢 Andar / Laje Corporativa | Corporate floor / Office floor", "🏢 Prédio Inteiro | Entire building", "🏢 Terrenos / Lotes Comerciais | Commercial land / Plots", "🏢 Galpão / Depósito / Armazém | Warehouse / Storage / Depot", "🏢 Garagem | Garage" ] } }, "amenities": { "title": "Which amenities should be included?", "uniqueItems": true, "type": "array", "description": "Leave this blank to search all listings regardless of amenities. Select one or more options to narrow the results.", "items": { "type": "string", "enum": [ "pets_allowed", "heating", "air_conditioning", "service_area", "builtin_wardrobe", "bedroom_wardrobe", "kitchen_cabinets", "bathroom_cabinets", "blindex_box", "gas_shower", "closet", "internet_access", "american_kitchen", "gourmet_kitchen", "large_kitchen", "home_office", "intercom", "large_window", "furnished", "backyard", "cable_tv", "balcony", "gourmet_balcony", "natural_ventilation", "bathtub", "panoramic_view", "freezer", "cooker", "deposit", "private_pool" ], "enumTitles": [ "✨ Aceita animais | Pets allowed", "✨ Aquecimento | Heating", "✨ Ar-condicionado | Air conditioning", "✨ Área de serviço | Laundry area", "✨ Armário embutido | Built-in wardrobe", "✨ Armário embutido no quarto | Built-in wardrobe in bedroom", "✨ Armário na cozinha | Kitchen cabinets", "✨ Armário no banheiro | Bathroom cabinets", "✨ Box blindex | Glass shower enclosure", "✨ Chuveiro a gás | Gas shower", "✨ Closet | Walk-in closet", "✨ Conexão à internet | Internet connection", "✨ Cozinha americana | Open-plan kitchen", "✨ Cozinha gourmet | Gourmet kitchen", "✨ Cozinha grande | Large kitchen", "✨ Escritório | Home office", "✨ Interfone | Intercom", "✨ Janela grande | Large windows", "✨ Mobiliado | Furnished", "✨ Quintal | Backyard", "✨ TV a cabo | Cable TV", "✨ Varanda | Balcony", "✨ Varanda gourmet | Gourmet balcony", "✨ Ventilação natural | Natural ventilation", "✨ Banheira | Bathtub", "✨ Vista panorâmica | Panoramic view", "✨ Freezer | Freezer", "✨ Fogão | Cooker", "✨ Depósito | Deposit", "✨ Piscina privativa | Private pool" ] } }, "min_bedroom": { "title": "Minimum bedrooms", "enum": [ "1", "2", "3", "4" ], "type": "string", "description": "Choose the minimum number of bedrooms to include. Example: `2+` keeps listings with 2, 3, or 4 bedrooms." }, "min_bathroom": { "title": "Minimum bathrooms", "enum": [ "1", "2", "3", "4" ], "type": "string", "description": "Choose the minimum number of bathrooms to include. Example: `2+` keeps listings with 2, 3, or 4 bathrooms." }, "min_parking": { "title": "Minimum parking spaces", "enum": [ "1", "2", "3", "4" ], "type": "string", "description": "Choose the minimum number of parking spaces to include. Example: `1+` keeps listings with 1, 2, 3, or 4 spaces." }, "min_price": { "title": "Lowest price to include", "minimum": 0, "type": "integer", "description": "Enter the minimum listing price. Example: `400000` keeps properties priced at 400,000 and above." }, "max_price": { "title": "Highest price to include", "minimum": 0, "type": "integer", "description": "Enter the maximum listing price. Example: `3000000` keeps properties priced at 3,000,000 and below." }, "min_sqm": { "title": "Smallest usable area to include (sqm)", "minimum": 0, "type": "integer", "description": "Enter the minimum usable area in square meters. Example: `35` keeps listings with 35 sqm or more." }, "max_sqm": { "title": "Largest usable area to include (sqm)", "minimum": 0, "type": "integer", "description": "Enter the maximum usable area in square meters. Example: `100` keeps listings with 100 sqm or less." }, "near_transit": { "title": "Only show listings near transit", "type": "boolean", "description": "Enable this to filter for properties that VivaReal tags as close to metro, train, or other transit access.", "default": false }, "below_market_price": { "title": "Only show below-market deals", "type": "boolean", "description": "Enable this to keep only listings with VivaReal's below-market pricing badge.", "default": false }, "limit": { "title": "Maximum results per search", "minimum": 1, "type": "integer", "description": "Set how many listings to save for this run. Leave it empty to collect everything available for the selected search." }, "maximize_coverage": { "title": "Maximize coverage on large searches", "type": "boolean", "description": "Use this option to improve coverage for searches that return very large numbers of listings. It is recommended when you want the most complete results possible for your selected criteria.", "default": true } } }, "runsResponseSchema": { "type": "object", "properties": { "data": { "type": "object", "properties": { "id": { "type": "string" }, "actId": { "type": "string" }, "userId": { "type": "string" }, "startedAt": { "type": "string", "format": "date-time", "example": "2025-01-08T00:00:00.000Z" }, "finishedAt": { "type": "string", "format": "date-time", "example": "2025-01-08T00:00:00.000Z" }, "status": { "type": "string", "example": "READY" }, "meta": { "type": "object", "properties": { "origin": { "type": "string", "example": "API" }, "userAgent": { "type": "string" } } }, "stats": { "type": "object", "properties": { "inputBodyLen": { "type": "integer", "example": 2000 }, "rebootCount": { "type": "integer", "example": 0 }, "restartCount": { "type": "integer", "example": 0 }, "resurrectCount": { "type": "integer", "example": 0 }, "computeUnits": { "type": "integer", "example": 0 } } }, "options": { "type": "object", "properties": { "build": { "type": "string", "example": "latest" }, "timeoutSecs": { "type": "integer", "example": 300 }, "memoryMbytes": { "type": "integer", "example": 1024 }, "diskMbytes": { "type": "integer", "example": 2048 } } }, "buildId": { "type": "string" }, "defaultKeyValueStoreId": { "type": "string" }, "defaultDatasetId": { "type": "string" }, "defaultRequestQueueId": { "type": "string" }, "buildNumber": { "type": "string", "example": "1.0.0" }, "containerUrl": { "type": "string" }, "usage": { "type": "object", "properties": { "ACTOR_COMPUTE_UNITS": { "type": "integer", "example": 0 }, "DATASET_READS": { "type": "integer", "example": 0 }, "DATASET_WRITES": { "type": "integer", "example": 0 }, "KEY_VALUE_STORE_READS": { "type": "integer", "example": 0 }, "KEY_VALUE_STORE_WRITES": { "type": "integer", "example": 1 }, "KEY_VALUE_STORE_LISTS": { "type": "integer", "example": 0 }, "REQUEST_QUEUE_READS": { "type": "integer", "example": 0 }, "REQUEST_QUEUE_WRITES": { "type": "integer", "example": 0 }, "DATA_TRANSFER_INTERNAL_GBYTES": { "type": "integer", "example": 0 }, "DATA_TRANSFER_EXTERNAL_GBYTES": { "type": "integer", "example": 0 }, "PROXY_RESIDENTIAL_TRANSFER_GBYTES": { "type": "integer", "example": 0 }, "PROXY_SERPS": { "type": "integer", "example": 0 } } }, "usageTotalUsd": { "type": "number", "example": 0.00005 }, "usageUsd": { "type": "object", "properties": { "ACTOR_COMPUTE_UNITS": { "type": "integer", "example": 0 }, "DATASET_READS": { "type": "integer", "example": 0 }, "DATASET_WRITES": { "type": "integer", "example": 0 }, "KEY_VALUE_STORE_READS": { "type": "integer", "example": 0 }, "KEY_VALUE_STORE_WRITES": { "type": "number", "example": 0.00005 }, "KEY_VALUE_STORE_LISTS": { "type": "integer", "example": 0 }, "REQUEST_QUEUE_READS": { "type": "integer", "example": 0 }, "REQUEST_QUEUE_WRITES": { "type": "integer", "example": 0 }, "DATA_TRANSFER_INTERNAL_GBYTES": { "type": "integer", "example": 0 }, "DATA_TRANSFER_EXTERNAL_GBYTES": { "type": "integer", "example": 0 }, "PROXY_RESIDENTIAL_TRANSFER_GBYTES": { "type": "integer", "example": 0 }, "PROXY_SERPS": { "type": "integer", "example": 0 } } } } } } } } } } ```