{
  "data": {
    "id": "qV2ux6HuxEezQno99",
    "actId": "Mz9MrwVRNHun4oNiK",
    "userId": "zq8lKbpLzTjGDayPC",
    "startedAt": "2026-10-24T13:09:34.255Z",
    "finishedAt": "2026-10-24T13:09:46.488Z",
    "status": "SUCCEEDED",
    "meta": {
      "origin": "CLI"
    },
    "stats": {
      "durationMillis": 12128,
      "runTimeSecs": 12.128,
      "computeUnits": 0.013475555555555555,
      "imageSizeBytes": 355088384
    },
    "options": {
      "useCache": true,
      "betaPackages": false,
      "memoryMbytes": 4096,
      "diskMbytes": 8192
    },
    "createdByOrganizationMemberUserId": "GK9YjZRyQZVzOdoH5",
    "exitCode": 0,
    "inputSchema": "{\n  \"title\": \"VivaReal Brazil Scraper Input\",\n  \"description\": \"Search VivaReal Brazil by city, state, neighborhood, price, area, rooms, property type, and amenities, or look up specific listing URLs/IDs.\",\n  \"type\": \"object\",\n  \"schemaVersion\": 1,\n  \"properties\": {\n    \"mode\": {\n      \"title\": \"Mode\",\n      \"type\": \"string\",\n      \"description\": \"Search a Brazilian city for sale/rent listings, or fetch specific listings by URL or ID.\",\n      \"editor\": \"select\",\n      \"enum\": [\n        \"sale\",\n        \"rent\",\n        \"byUrls\",\n        \"searchForSale\",\n        \"searchForRent\"\n      ],\n      \"enumTitles\": [\n        \"Properties for sale\",\n        \"Properties for rent\",\n        \"Look up listings by URL or ID\",\n        \"Properties for sale (legacy saved task)\",\n        \"Properties for rent (legacy saved task)\"\n      ],\n      \"default\": \"sale\",\n      \"prefill\": \"sale\"\n    },\n    \"city\": {\n      \"title\": \"City\",\n      \"type\": \"string\",\n      \"description\": \"Brazilian city to search, for example São Paulo, Rio de Janeiro, or Belo Horizonte. Use with State.\",\n      \"editor\": \"textfield\",\n      \"default\": \"São Paulo\",\n      \"prefill\": \"São Paulo\"\n    },\n    \"state\": {\n      \"title\": \"State\",\n      \"type\": \"string\",\n      \"description\": \"Brazilian state (UF) that contains the city.\",\n      \"editor\": \"select\",\n      \"enum\": [\n        \"AC\",\n        \"AL\",\n        \"AP\",\n        \"AM\",\n        \"BA\",\n        \"CE\",\n        \"DF\",\n        \"ES\",\n        \"GO\",\n        \"MA\",\n        \"MT\",\n        \"MS\",\n        \"MG\",\n        \"PA\",\n        \"PB\",\n        \"PR\",\n        \"PE\",\n        \"PI\",\n        \"RJ\",\n        \"RN\",\n        \"RS\",\n        \"RO\",\n        \"RR\",\n        \"SC\",\n        \"SP\",\n        \"SE\",\n        \"TO\"\n      ],\n      \"enumTitles\": [\n        \"Acre\",\n        \"Alagoas\",\n        \"Amapá\",\n        \"Amazonas\",\n        \"Bahia\",\n        \"Ceará\",\n        \"Distrito Federal\",\n        \"Espírito Santo\",\n        \"Goiás\",\n        \"Maranhão\",\n        \"Mato Grosso\",\n        \"Mato Grosso do Sul\",\n        \"Minas Gerais\",\n        \"Pará\",\n        \"Paraíba\",\n        \"Paraná\",\n        \"Pernambuco\",\n        \"Piauí\",\n        \"Rio de Janeiro\",\n        \"Rio Grande do Norte\",\n        \"Rio Grande do Sul\",\n        \"Rondônia\",\n        \"Roraima\",\n        \"Santa Catarina\",\n        \"São Paulo\",\n        \"Sergipe\",\n        \"Tocantins\"\n      ],\n      \"default\": \"SP\",\n      \"prefill\": \"SP\"\n    },\n    \"neighborhood\": {\n      \"title\": \"Neighborhood\",\n      \"type\": \"string\",\n      \"description\": \"Optional neighborhood within the city, for example Pinheiros or Copacabana.\",\n      \"editor\": \"textfield\"\n    },\n    \"propertyType\": {\n      \"title\": \"Property Type\",\n      \"type\": \"string\",\n      \"description\": \"Filter by property type. Legacy values TERRAIN and COMMERCIAL still work.\",\n      \"editor\": \"select\",\n      \"enum\": [\n        \"ANY\",\n        \"APARTMENT\",\n        \"HOME\",\n        \"PENTHOUSE\",\n        \"FLAT\",\n        \"KITNET\",\n        \"OFFICE\",\n        \"ALLOTMENT_LAND\",\n        \"COMMERCIAL_PROPERTY\",\n        \"COMMERCIAL_BUILDING\",\n        \"WAREHOUSE\",\n        \"GARAGE\",\n        \"FARM\",\n        \"HOTEL\",\n        \"TERRAIN\",\n        \"COMMERCIAL\"\n      ],\n      \"enumTitles\": [\n        \"Any type\",\n        \"Apartment\",\n        \"House\",\n        \"Penthouse\",\n        \"Flat\",\n        \"Kitnet / studio\",\n        \"Office\",\n        \"Land / lot\",\n        \"Commercial property\",\n        \"Commercial building\",\n        \"Warehouse\",\n        \"Garage\",\n        \"Farm\",\n        \"Hotel\",\n        \"Land (legacy alias)\",\n        \"Commercial (legacy alias)\"\n      ],\n      \"default\": \"ANY\",\n      \"prefill\": \"ANY\"\n    },\n    \"usageType\": {\n      \"title\": \"Usage\",\n      \"type\": \"string\",\n      \"description\": \"Residential, commercial, or any usage.\",\n      \"editor\": \"select\",\n      \"enum\": [\n        \"ANY\",\n        \"RESIDENTIAL\",\n        \"COMMERCIAL\"\n      ],\n      \"enumTitles\": [\n        \"Any usage\",\n        \"Residential\",\n        \"Commercial\"\n      ],\n      \"default\": \"ANY\",\n      \"prefill\": \"ANY\"\n    },\n    \"listingType\": {\n      \"title\": \"Listing Type\",\n      \"type\": \"string\",\n      \"description\": \"Used resale listings, new-development listings, or both.\",\n      \"editor\": \"select\",\n      \"enum\": [\n        \"USED\",\n        \"DEVELOPMENT\",\n        \"ALL\"\n      ],\n      \"enumTitles\": [\n        \"Used / resale\",\n        \"New development\",\n        \"Both\"\n      ],\n      \"default\": \"USED\",\n      \"prefill\": \"USED\"\n    },\n    \"priceMin\": {\n      \"title\": \"Min Price (BRL)\",\n      \"type\": \"integer\",\n      \"description\": \"Minimum price in Brazilian reais. Not Colombian pesos.\",\n      \"minimum\": 0,\n      \"maximum\": 10000000000\n    },\n    \"priceMax\": {\n      \"title\": \"Max Price (BRL)\",\n      \"type\": \"integer\",\n      \"description\": \"Maximum price in Brazilian reais. Not Colombian pesos.\",\n      \"minimum\": 0,\n      \"maximum\": 10000000000\n    },\n    \"bedroomsMin\": {\n      \"title\": \"Min Bedrooms\",\n      \"type\": \"integer\",\n      \"description\": \"Minimum number of bedrooms.\",\n      \"minimum\": 0,\n      \"maximum\": 20\n    },\n    \"bedroomsMax\": {\n      \"title\": \"Max Bedrooms\",\n      \"type\": \"integer\",\n      \"description\": \"Maximum number of bedrooms.\",\n      \"minimum\": 0,\n      \"maximum\": 20\n    },\n    \"bathroomsMin\": {\n      \"title\": \"Min Bathrooms\",\n      \"type\": \"integer\",\n      \"description\": \"Minimum number of bathrooms.\",\n      \"minimum\": 0,\n      \"maximum\": 20\n    },\n    \"bathroomsMax\": {\n      \"title\": \"Max Bathrooms\",\n      \"type\": \"integer\",\n      \"description\": \"Maximum number of bathrooms.\",\n      \"minimum\": 0,\n      \"maximum\": 20\n    },\n    \"parkingMin\": {\n      \"title\": \"Min Parking Spaces\",\n      \"type\": \"integer\",\n      \"description\": \"Minimum number of parking spaces.\",\n      \"minimum\": 0,\n      \"maximum\": 20\n    },\n    \"areaMin\": {\n      \"title\": \"Min Usable Area (m²)\",\n      \"type\": \"integer\",\n      \"description\": \"Minimum usable area in square meters.\",\n      \"minimum\": 0,\n      \"maximum\": 100000\n    },\n    \"areaMax\": {\n      \"title\": \"Max Usable Area (m²)\",\n      \"type\": \"integer\",\n      \"description\": \"Maximum usable area in square meters.\",\n      \"minimum\": 0,\n      \"maximum\": 100000\n    },\n    \"amenities\": {\n      \"title\": \"Amenities\",\n      \"type\": \"array\",\n      \"description\": \"Optional amenity codes the listing must have, for example POOL, GYM, ELEVATOR, BARBECUE_GRILL, or PETS_ALLOWED.\",\n      \"editor\": \"stringList\",\n      \"items\": {\n        \"type\": \"string\"\n      }\n    },\n    \"listingUrls\": {\n      \"title\": \"Listing URLs or IDs\",\n      \"type\": \"array\",\n      \"description\": \"VivaReal listing URLs or numeric IDs to fetch (mode=byUrls). Example: https://www.vivareal.com.br/imovel/2918839249/\",\n      \"editor\": \"stringList\",\n      \"items\": {\n        \"type\": \"string\"\n      }\n    },\n    \"maxItems\": {\n      \"title\": \"Max Items\",\n      \"type\": \"integer\",\n      \"description\": \"Maximum number of listings to return.\",\n      \"minimum\": 1,\n      \"maximum\": 1000,\n      \"default\": 50,\n      \"prefill\": 3\n    }\n  },\n  \"required\": [\n    \"mode\"\n  ]\n}",
    "readme": "# VivaReal Brazil Real Estate Listings by City & Price\n\nScrape **VivaReal Brazil** (vivareal.com.br) for homes for sale or rent in any Brazilian city. Records carry the BRL price, condo fee, IPTU, usable and total area, room counts, street address and coordinates, amenities, every listing photo, the advertiser's public contact details, and a working listing URL whenever VivaReal publishes them. Search by city, state, and neighborhood, or paste specific listing URLs/IDs to get full titles, descriptions, and detail-fresh fields. Search records come from VivaReal's search index; `byUrls` reads the detail endpoint and is the freshest source for descriptions, images, contact details, and timestamps.\n\n> VivaReal Colombia (vivareal.com.co) has been offline since 2024 and returns HTTP 410. The live VivaReal marketplace is the Brazilian one. This actor's historical slug still says \"Colombia\", but it now scrapes VivaReal **Brazil** only. Bogotá or other Colombian inputs return zero records with a clear status message — no invented data.\n\n## What this actor does\n\n- **Three modes:** `sale`, `rent`, and `byUrls` (VivaReal listing URLs or numeric IDs).\n- **City searches:** combine city + state, optionally narrow to a neighborhood.\n- **Server + client filters:** price, usable area, bedrooms, bathrooms, parking, property type, usage type, listing type (`USED`, `DEVELOPMENT`, or both), and amenities.\n- **Complete property record:** condo fee, IPTU with period, usable and total area, suites, coordinates, amenities, all photos, advertiser name/licence/phones, WhatsApp, and timestamps (`createdAt` in search; `createdAt` + `updatedAt` in `byUrls`).\n- **Deep pagination:** up to 1,000 listings per run, deduplicated by listing ID.\n- **Empty fields are omitted** — a missing value is never emitted as `null`, `\"\"`, or `[]`.\n\n## Output per listing\n\n| Field | Description |\n|---|---|\n| `listingId` | VivaReal listing identifier |\n| `title` | Portal title when available (`byUrls`, or the search `h2Tag`); otherwise a composed title |\n| `titleSource` | `portal` when the title came from VivaReal, `generated` when composed |\n| `description` | Full description (mode=`byUrls` only; search results do not include it) |\n| `price`, `currency` | Asking price and `BRL` |\n| `condoFee` | Monthly condo fee in BRL, when published |\n| `iptu`, `iptuPeriod` | IPTU value and period (`yearly` or `monthly`) |\n| `area` | Usable area in m² |\n| `totalArea` | Total area in m², when published |\n| `bedrooms`, `bathrooms`, `suites`, `parkingSpaces` | Room and parking counts |\n| `propertyType`, `propertyTypeLabel` | VivaReal code and Portuguese label (`APARTMENT` / `Apartamento`, etc.) |\n| `usageType` | `RESIDENTIAL` or `COMMERCIAL` |\n| `transactionType` | `sale` or `rental` from the listing's pricing block |\n| `listingType` | `used` or `development` |\n| `street`, `streetNumber`, `neighborhood`, `city`, `state`, `stateCode`, `zipCode` | Address parts |\n| `address` | Readable address string built from the available parts |\n| `latitude`, `longitude` | Exact map coordinates when available; approximate-location listings may omit them |\n| `amenities` | Amenity codes such as `POOL`, `GYM`, `ELEVATOR`, `BARBECUE_GRILL` |\n| `images` | Every listing photo, in source order |\n| `imageUrl` | First photo |\n| `advertiserName`, `advertiserLicense` | Advertiser/agency name and licence number |\n| `advertiserPhones` | Public phone numbers |\n| `whatsapp` | Public WhatsApp number, when published |\n| `createdAt`, `updatedAt` | Listing timestamps; `updatedAt` is returned in `byUrls` and omitted in search (the search API does not return it) |\n| `listingUrl` | `https://www.vivareal.com.br/imovel/<id>/` |\n| `mode` | `sale`, `rent`, or `byUrls` |\n| `recordType` | Always `property` |\n| `scrapedAt` | ISO 8601 timestamp of the scrape |\n\n## Input\n\n| Field | Type | Default | Description |\n|---|---|---|---|\n| `mode` | string | `sale` | `sale`, `rent`, or `byUrls` |\n| `city` | string | `São Paulo` | Brazilian city to search |\n| `state` | string | `SP` | Brazilian state (UF) |\n| `neighborhood` | string | – | Optional neighborhood within the city |\n| `propertyType` | string | `ANY` | Any type, apartment, house, penthouse, flat, kitnet, office, land, commercial, warehouse, garage, farm, or hotel |\n| `usageType` | string | `ANY` | `ANY`, `RESIDENTIAL`, or `COMMERCIAL` |\n| `listingType` | string | `USED` | `USED`, `DEVELOPMENT`, or `ALL` |\n| `priceMin`, `priceMax` | integer | – | Price range in BRL |\n| `bedroomsMin`, `bedroomsMax` | integer | – | Bedroom range |\n| `bathroomsMin`, `bathroomsMax` | integer | – | Bathroom range |\n| `parkingMin` | integer | – | Minimum parking spaces (search currently applies this as an exact match; see Limitations) |\n| `areaMin`, `areaMax` | integer | – | Usable area range in m² |\n| `amenities` | array | – | Required amenity codes (all must match) |\n| `listingUrls` | array | – | VivaReal URLs or numeric IDs (mode=`byUrls`) |\n| `maxItems` | integer | `50` | Maximum records to return (1–1000) |\n\nLegacy saved tasks still work: `mode` values `searchForSale` / `searchForRent` are treated as `sale` / `rent`, and `propertyType` values `TERRAIN` / `COMMERCIAL` are treated as land / commercial property.\n\n### Example: apartments for sale in São Paulo\n\n```json\n{\n  \"mode\": \"sale\",\n  \"city\": \"São Paulo\",\n  \"state\": \"SP\",\n  \"propertyType\": \"APARTMENT\",\n  \"priceMin\": 400000,\n  \"priceMax\": 900000,\n  \"bedroomsMin\": 2,\n  \"areaMin\": 60,\n  \"maxItems\": 100\n}\n```\n\n### Example: houses for rent in Rio de Janeiro\n\n```json\n{\n  \"mode\": \"rent\",\n  \"city\": \"Rio de Janeiro\",\n  \"state\": \"RJ\",\n  \"neighborhood\": \"Copacabana\",\n  \"propertyType\": \"HOME\",\n  \"parkingMin\": 1,\n  \"maxItems\": 50\n}\n```\n\n### Example: listing lookup by URL\n\n```json\n{\n  \"mode\": \"byUrls\",\n  \"listingUrls\": [\n    \"https://www.vivareal.com.br/imovel/2918839249/\",\n    \"2918720977\"\n  ]\n}\n```\n\n### Example: amenities and area in Belo Horizonte\n\n```json\n{\n  \"mode\": \"sale\",\n  \"city\": \"Belo Horizonte\",\n  \"state\": \"MG\",\n  \"amenities\": [\"POOL\", \"GYM\", \"ELEVATOR\"],\n  \"areaMin\": 80,\n  \"areaMax\": 200,\n  \"listingType\": \"USED\",\n  \"maxItems\": 30\n}\n```\n\n## Use cases\n\n- **Market research** — compare asking prices, condo fees, and IPTU across Brazilian cities and neighborhoods.\n- **Lead generation** — build a current list of active listings with advertiser phone and WhatsApp contacts.\n- **Investment screening** — filter by price, area, rooms, and amenities to shortlist candidate properties.\n- **Rental monitoring** — track rent asking prices and availability in a target neighborhood.\n- **Proptech data feeds** — power a search, valuation, or comparison product with live VivaReal inventory.\n\n## FAQ\n\n**Which cities can I search?**\nAny Brazilian city covered by VivaReal, including São Paulo, Rio de Janeiro, Belo Horizonte, Curitiba, Porto Alegre, Salvador, Recife, Fortaleza, and Brasília. Pass the city name in `city` and its state in `state`.\n\n**What currency are prices in?**\nBrazilian reais (BRL). VivaReal Brazil lists prices in BRL. The actor does not convert values or apply legacy COP amounts.\n\n**Why does the title look generated in search results?**\nVivaReal's search API does not return a title for most listings, and some of the `h2Tag` titles it does return are truncated. The actor uses the portal title when one exists, otherwise it composes a readable title from the property type, bedroom count, neighborhood, and city, and marks it with `titleSource: \"generated\"`. Use `byUrls` for the full portal title.\n\n**Why is `description` missing from search results?**\nDescriptions are not part of VivaReal's search response. Use `mode: \"byUrls\"` with listing URLs or IDs to fetch full titles, descriptions, and updated timestamps.\n\n**What does `iptuPeriod` mean?**\nIt tells you whether the IPTU value is yearly or monthly. Search mode follows the search API's `yearlyIptu` field; the detail response (and `byUrls`) can mark the same value monthly. The actor preserves the period from the response it used instead of silently converting it, so use `byUrls` for detail-consistent periods.\n\n**How many listings can I get in one run?**\nUp to 1,000 via `maxItems`. The actor pages through VivaReal at 30 listings per page. A very broad, rarity-filtered search can hit the 5,000-row scan limit; narrow the city, neighborhood, price, or property type for deeper coverage.\n\n**Why are some fields missing from individual records?**\nVivaReal does not publish every field for every listing, and approximate-location listings can lack a street number or exact coordinates. The actor omits a missing field rather than guessing or filling it with a placeholder. Search records can also lag the live detail page; use `byUrls` for the freshest values.\n\n**Can I search VivaReal Colombia or Bogotá?**\nNo. VivaReal Colombia is offline. Colombian city names return zero records with a status message explaining that the actor now covers Brazil.\n\n**Do I need a VivaReal account, login, or proxy?**\nNo. The actor reads public VivaReal listings and chooses a working connection automatically. Just fill in the input and run it.\n\n**Is this affiliated with VivaReal?**\nNo. This is an independent, third-party actor that reads VivaReal's public listing data and is not operated by or affiliated with VivaReal.\n\n## Limitations\n\n- **No descriptions in search:** only `byUrls` returns the full description.\n- **Composed titles:** most search records use a generated title because the search API omits the portal title.\n- **Search-index freshness:** `sale`/`rent` records come from VivaReal's search index. Area, room counts, neighborhood, and IPTU period can differ from the live listing page; `byUrls` returns detail-fresh values. In the 2026-10-24 25-listing check, 2/15 sale records had stale area/room/parking values, 6/15 had a different neighborhood, and 7/10 rent records reported a yearly IPTU period that the page marked monthly.\n- **Parking filter:** in search, `parkingMin` currently acts as an exact `parkingSpaces` match, so listings with more spaces can be missed. The intended minimum semantics require a code fix; use `byUrls` or omit the filter until then.\n- **Approximate locations:** listings whose map point is approximate can omit `streetNumber`, `latitude`, and `longitude`, even though the page shows a neighborhood-level pin.\n- **Truncated search titles:** some search `h2Tag` titles are truncated; `byUrls` returns the full portal title.\n- **IPTU period ambiguity:** search mode follows the search API's `yearlyIptu`; the detail response (and `byUrls`) can mark the same value monthly. Use `byUrls` for detail-consistent periods.\n- **Source caps:** VivaReal returns at most 30 listings per page. A run scans at most 5,000 rows before reporting a shortfall.\n- **Photo quality:** images are requested at 1024×768 and may be unavailable if VivaReal removed them.\n- **Brazil only:** there is no Colombian inventory, no ZAP Imóveis data, and no virtual tours or videos.\n",
    "actorDefinition": {
      "actorSpecification": 1,
      "name": "vivareal-colombia-real-estate-listings-by-city",
      "title": "VivaReal Brazil Real Estate Listings by City & Price",
      "description": "Scrape VivaReal Brazil by city and neighborhood for sale or rent. Get BRL prices, condo fee, IPTU, areas, rooms, coordinates, amenities, all photos, advertiser contacts, WhatsApp, and listing URLs. Look up listings by URL or ID for full details.",
      "version": "1.1",
      "buildTag": "latest",
      "dockerfile": "./Dockerfile",
      "readme": "# VivaReal Brazil Real Estate Listings by City & Price\n\nScrape **VivaReal Brazil** (vivareal.com.br) for homes for sale or rent in any Brazilian city. Records carry the BRL price, condo fee, IPTU, usable and total area, room counts, street address and coordinates, amenities, every listing photo, the advertiser's public contact details, and a working listing URL whenever VivaReal publishes them. Search by city, state, and neighborhood, or paste specific listing URLs/IDs to get full titles, descriptions, and detail-fresh fields. Search records come from VivaReal's search index; `byUrls` reads the detail endpoint and is the freshest source for descriptions, images, contact details, and timestamps.\n\n> VivaReal Colombia (vivareal.com.co) has been offline since 2024 and returns HTTP 410. The live VivaReal marketplace is the Brazilian one. This actor's historical slug still says \"Colombia\", but it now scrapes VivaReal **Brazil** only. Bogotá or other Colombian inputs return zero records with a clear status message — no invented data.\n\n## What this actor does\n\n- **Three modes:** `sale`, `rent`, and `byUrls` (VivaReal listing URLs or numeric IDs).\n- **City searches:** combine city + state, optionally narrow to a neighborhood.\n- **Server + client filters:** price, usable area, bedrooms, bathrooms, parking, property type, usage type, listing type (`USED`, `DEVELOPMENT`, or both), and amenities.\n- **Complete property record:** condo fee, IPTU with period, usable and total area, suites, coordinates, amenities, all photos, advertiser name/licence/phones, WhatsApp, and timestamps (`createdAt` in search; `createdAt` + `updatedAt` in `byUrls`).\n- **Deep pagination:** up to 1,000 listings per run, deduplicated by listing ID.\n- **Empty fields are omitted** — a missing value is never emitted as `null`, `\"\"`, or `[]`.\n\n## Output per listing\n\n| Field | Description |\n|---|---|\n| `listingId` | VivaReal listing identifier |\n| `title` | Portal title when available (`byUrls`, or the search `h2Tag`); otherwise a composed title |\n| `titleSource` | `portal` when the title came from VivaReal, `generated` when composed |\n| `description` | Full description (mode=`byUrls` only; search results do not include it) |\n| `price`, `currency` | Asking price and `BRL` |\n| `condoFee` | Monthly condo fee in BRL, when published |\n| `iptu`, `iptuPeriod` | IPTU value and period (`yearly` or `monthly`) |\n| `area` | Usable area in m² |\n| `totalArea` | Total area in m², when published |\n| `bedrooms`, `bathrooms`, `suites`, `parkingSpaces` | Room and parking counts |\n| `propertyType`, `propertyTypeLabel` | VivaReal code and Portuguese label (`APARTMENT` / `Apartamento`, etc.) |\n| `usageType` | `RESIDENTIAL` or `COMMERCIAL` |\n| `transactionType` | `sale` or `rental` from the listing's pricing block |\n| `listingType` | `used` or `development` |\n| `street`, `streetNumber`, `neighborhood`, `city`, `state`, `stateCode`, `zipCode` | Address parts |\n| `address` | Readable address string built from the available parts |\n| `latitude`, `longitude` | Exact map coordinates when available; approximate-location listings may omit them |\n| `amenities` | Amenity codes such as `POOL`, `GYM`, `ELEVATOR`, `BARBECUE_GRILL` |\n| `images` | Every listing photo, in source order |\n| `imageUrl` | First photo |\n| `advertiserName`, `advertiserLicense` | Advertiser/agency name and licence number |\n| `advertiserPhones` | Public phone numbers |\n| `whatsapp` | Public WhatsApp number, when published |\n| `createdAt`, `updatedAt` | Listing timestamps; `updatedAt` is returned in `byUrls` and omitted in search (the search API does not return it) |\n| `listingUrl` | `https://www.vivareal.com.br/imovel/<id>/` |\n| `mode` | `sale`, `rent`, or `byUrls` |\n| `recordType` | Always `property` |\n| `scrapedAt` | ISO 8601 timestamp of the scrape |\n\n## Input\n\n| Field | Type | Default | Description |\n|---|---|---|---|\n| `mode` | string | `sale` | `sale`, `rent`, or `byUrls` |\n| `city` | string | `São Paulo` | Brazilian city to search |\n| `state` | string | `SP` | Brazilian state (UF) |\n| `neighborhood` | string | – | Optional neighborhood within the city |\n| `propertyType` | string | `ANY` | Any type, apartment, house, penthouse, flat, kitnet, office, land, commercial, warehouse, garage, farm, or hotel |\n| `usageType` | string | `ANY` | `ANY`, `RESIDENTIAL`, or `COMMERCIAL` |\n| `listingType` | string | `USED` | `USED`, `DEVELOPMENT`, or `ALL` |\n| `priceMin`, `priceMax` | integer | – | Price range in BRL |\n| `bedroomsMin`, `bedroomsMax` | integer | – | Bedroom range |\n| `bathroomsMin`, `bathroomsMax` | integer | – | Bathroom range |\n| `parkingMin` | integer | – | Minimum parking spaces (search currently applies this as an exact match; see Limitations) |\n| `areaMin`, `areaMax` | integer | – | Usable area range in m² |\n| `amenities` | array | – | Required amenity codes (all must match) |\n| `listingUrls` | array | – | VivaReal URLs or numeric IDs (mode=`byUrls`) |\n| `maxItems` | integer | `50` | Maximum records to return (1–1000) |\n\nLegacy saved tasks still work: `mode` values `searchForSale` / `searchForRent` are treated as `sale` / `rent`, and `propertyType` values `TERRAIN` / `COMMERCIAL` are treated as land / commercial property.\n\n### Example: apartments for sale in São Paulo\n\n```json\n{\n  \"mode\": \"sale\",\n  \"city\": \"São Paulo\",\n  \"state\": \"SP\",\n  \"propertyType\": \"APARTMENT\",\n  \"priceMin\": 400000,\n  \"priceMax\": 900000,\n  \"bedroomsMin\": 2,\n  \"areaMin\": 60,\n  \"maxItems\": 100\n}\n```\n\n### Example: houses for rent in Rio de Janeiro\n\n```json\n{\n  \"mode\": \"rent\",\n  \"city\": \"Rio de Janeiro\",\n  \"state\": \"RJ\",\n  \"neighborhood\": \"Copacabana\",\n  \"propertyType\": \"HOME\",\n  \"parkingMin\": 1,\n  \"maxItems\": 50\n}\n```\n\n### Example: listing lookup by URL\n\n```json\n{\n  \"mode\": \"byUrls\",\n  \"listingUrls\": [\n    \"https://www.vivareal.com.br/imovel/2918839249/\",\n    \"2918720977\"\n  ]\n}\n```\n\n### Example: amenities and area in Belo Horizonte\n\n```json\n{\n  \"mode\": \"sale\",\n  \"city\": \"Belo Horizonte\",\n  \"state\": \"MG\",\n  \"amenities\": [\"POOL\", \"GYM\", \"ELEVATOR\"],\n  \"areaMin\": 80,\n  \"areaMax\": 200,\n  \"listingType\": \"USED\",\n  \"maxItems\": 30\n}\n```\n\n## Use cases\n\n- **Market research** — compare asking prices, condo fees, and IPTU across Brazilian cities and neighborhoods.\n- **Lead generation** — build a current list of active listings with advertiser phone and WhatsApp contacts.\n- **Investment screening** — filter by price, area, rooms, and amenities to shortlist candidate properties.\n- **Rental monitoring** — track rent asking prices and availability in a target neighborhood.\n- **Proptech data feeds** — power a search, valuation, or comparison product with live VivaReal inventory.\n\n## FAQ\n\n**Which cities can I search?**\nAny Brazilian city covered by VivaReal, including São Paulo, Rio de Janeiro, Belo Horizonte, Curitiba, Porto Alegre, Salvador, Recife, Fortaleza, and Brasília. Pass the city name in `city` and its state in `state`.\n\n**What currency are prices in?**\nBrazilian reais (BRL). VivaReal Brazil lists prices in BRL. The actor does not convert values or apply legacy COP amounts.\n\n**Why does the title look generated in search results?**\nVivaReal's search API does not return a title for most listings, and some of the `h2Tag` titles it does return are truncated. The actor uses the portal title when one exists, otherwise it composes a readable title from the property type, bedroom count, neighborhood, and city, and marks it with `titleSource: \"generated\"`. Use `byUrls` for the full portal title.\n\n**Why is `description` missing from search results?**\nDescriptions are not part of VivaReal's search response. Use `mode: \"byUrls\"` with listing URLs or IDs to fetch full titles, descriptions, and updated timestamps.\n\n**What does `iptuPeriod` mean?**\nIt tells you whether the IPTU value is yearly or monthly. Search mode follows the search API's `yearlyIptu` field; the detail response (and `byUrls`) can mark the same value monthly. The actor preserves the period from the response it used instead of silently converting it, so use `byUrls` for detail-consistent periods.\n\n**How many listings can I get in one run?**\nUp to 1,000 via `maxItems`. The actor pages through VivaReal at 30 listings per page. A very broad, rarity-filtered search can hit the 5,000-row scan limit; narrow the city, neighborhood, price, or property type for deeper coverage.\n\n**Why are some fields missing from individual records?**\nVivaReal does not publish every field for every listing, and approximate-location listings can lack a street number or exact coordinates. The actor omits a missing field rather than guessing or filling it with a placeholder. Search records can also lag the live detail page; use `byUrls` for the freshest values.\n\n**Can I search VivaReal Colombia or Bogotá?**\nNo. VivaReal Colombia is offline. Colombian city names return zero records with a status message explaining that the actor now covers Brazil.\n\n**Do I need a VivaReal account, login, or proxy?**\nNo. The actor reads public VivaReal listings and chooses a working connection automatically. Just fill in the input and run it.\n\n**Is this affiliated with VivaReal?**\nNo. This is an independent, third-party actor that reads VivaReal's public listing data and is not operated by or affiliated with VivaReal.\n\n## Limitations\n\n- **No descriptions in search:** only `byUrls` returns the full description.\n- **Composed titles:** most search records use a generated title because the search API omits the portal title.\n- **Search-index freshness:** `sale`/`rent` records come from VivaReal's search index. Area, room counts, neighborhood, and IPTU period can differ from the live listing page; `byUrls` returns detail-fresh values. In the 2026-10-24 25-listing check, 2/15 sale records had stale area/room/parking values, 6/15 had a different neighborhood, and 7/10 rent records reported a yearly IPTU period that the page marked monthly.\n- **Parking filter:** in search, `parkingMin` currently acts as an exact `parkingSpaces` match, so listings with more spaces can be missed. The intended minimum semantics require a code fix; use `byUrls` or omit the filter until then.\n- **Approximate locations:** listings whose map point is approximate can omit `streetNumber`, `latitude`, and `longitude`, even though the page shows a neighborhood-level pin.\n- **Truncated search titles:** some search `h2Tag` titles are truncated; `byUrls` returns the full portal title.\n- **IPTU period ambiguity:** search mode follows the search API's `yearlyIptu`; the detail response (and `byUrls`) can mark the same value monthly. Use `byUrls` for detail-consistent periods.\n- **Source caps:** VivaReal returns at most 30 listings per page. A run scans at most 5,000 rows before reporting a shortfall.\n- **Photo quality:** images are requested at 1024×768 and may be unavailable if VivaReal removed them.\n- **Brazil only:** there is no Colombian inventory, no ZAP Imóveis data, and no virtual tours or videos.\n",
      "input": {
        "title": "VivaReal Brazil Scraper Input",
        "description": "Search VivaReal Brazil by city, state, neighborhood, price, area, rooms, property type, and amenities, or look up specific listing URLs/IDs.",
        "type": "object",
        "schemaVersion": 1,
        "properties": {
          "mode": {
            "title": "Mode",
            "type": "string",
            "description": "Search a Brazilian city for sale/rent listings, or fetch specific listings by URL or ID.",
            "editor": "select",
            "enum": [
              "sale",
              "rent",
              "byUrls",
              "searchForSale",
              "searchForRent"
            ],
            "enumTitles": [
              "Properties for sale",
              "Properties for rent",
              "Look up listings by URL or ID",
              "Properties for sale (legacy saved task)",
              "Properties for rent (legacy saved task)"
            ],
            "default": "sale",
            "prefill": "sale"
          },
          "city": {
            "title": "City",
            "type": "string",
            "description": "Brazilian city to search, for example São Paulo, Rio de Janeiro, or Belo Horizonte. Use with State.",
            "editor": "textfield",
            "default": "São Paulo",
            "prefill": "São Paulo"
          },
          "state": {
            "title": "State",
            "type": "string",
            "description": "Brazilian state (UF) that contains the city.",
            "editor": "select",
            "enum": [
              "AC",
              "AL",
              "AP",
              "AM",
              "BA",
              "CE",
              "DF",
              "ES",
              "GO",
              "MA",
              "MT",
              "MS",
              "MG",
              "PA",
              "PB",
              "PR",
              "PE",
              "PI",
              "RJ",
              "RN",
              "RS",
              "RO",
              "RR",
              "SC",
              "SP",
              "SE",
              "TO"
            ],
            "enumTitles": [
              "Acre",
              "Alagoas",
              "Amapá",
              "Amazonas",
              "Bahia",
              "Ceará",
              "Distrito Federal",
              "Espírito Santo",
              "Goiás",
              "Maranhão",
              "Mato Grosso",
              "Mato Grosso do Sul",
              "Minas Gerais",
              "Pará",
              "Paraíba",
              "Paraná",
              "Pernambuco",
              "Piauí",
              "Rio de Janeiro",
              "Rio Grande do Norte",
              "Rio Grande do Sul",
              "Rondônia",
              "Roraima",
              "Santa Catarina",
              "São Paulo",
              "Sergipe",
              "Tocantins"
            ],
            "default": "SP",
            "prefill": "SP"
          },
          "neighborhood": {
            "title": "Neighborhood",
            "type": "string",
            "description": "Optional neighborhood within the city, for example Pinheiros or Copacabana.",
            "editor": "textfield"
          },
          "propertyType": {
            "title": "Property Type",
            "type": "string",
            "description": "Filter by property type. Legacy values TERRAIN and COMMERCIAL still work.",
            "editor": "select",
            "enum": [
              "ANY",
              "APARTMENT",
              "HOME",
              "PENTHOUSE",
              "FLAT",
              "KITNET",
              "OFFICE",
              "ALLOTMENT_LAND",
              "COMMERCIAL_PROPERTY",
              "COMMERCIAL_BUILDING",
              "WAREHOUSE",
              "GARAGE",
              "FARM",
              "HOTEL",
              "TERRAIN",
              "COMMERCIAL"
            ],
            "enumTitles": [
              "Any type",
              "Apartment",
              "House",
              "Penthouse",
              "Flat",
              "Kitnet / studio",
              "Office",
              "Land / lot",
              "Commercial property",
              "Commercial building",
              "Warehouse",
              "Garage",
              "Farm",
              "Hotel",
              "Land (legacy alias)",
              "Commercial (legacy alias)"
            ],
            "default": "ANY",
            "prefill": "ANY"
          },
          "usageType": {
            "title": "Usage",
            "type": "string",
            "description": "Residential, commercial, or any usage.",
            "editor": "select",
            "enum": [
              "ANY",
              "RESIDENTIAL",
              "COMMERCIAL"
            ],
            "enumTitles": [
              "Any usage",
              "Residential",
              "Commercial"
            ],
            "default": "ANY",
            "prefill": "ANY"
          },
          "listingType": {
            "title": "Listing Type",
            "type": "string",
            "description": "Used resale listings, new-development listings, or both.",
            "editor": "select",
            "enum": [
              "USED",
              "DEVELOPMENT",
              "ALL"
            ],
            "enumTitles": [
              "Used / resale",
              "New development",
              "Both"
            ],
            "default": "USED",
            "prefill": "USED"
          },
          "priceMin": {
            "title": "Min Price (BRL)",
            "type": "integer",
            "description": "Minimum price in Brazilian reais. Not Colombian pesos.",
            "minimum": 0,
            "maximum": 10000000000
          },
          "priceMax": {
            "title": "Max Price (BRL)",
            "type": "integer",
            "description": "Maximum price in Brazilian reais. Not Colombian pesos.",
            "minimum": 0,
            "maximum": 10000000000
          },
          "bedroomsMin": {
            "title": "Min Bedrooms",
            "type": "integer",
            "description": "Minimum number of bedrooms.",
            "minimum": 0,
            "maximum": 20
          },
          "bedroomsMax": {
            "title": "Max Bedrooms",
            "type": "integer",
            "description": "Maximum number of bedrooms.",
            "minimum": 0,
            "maximum": 20
          },
          "bathroomsMin": {
            "title": "Min Bathrooms",
            "type": "integer",
            "description": "Minimum number of bathrooms.",
            "minimum": 0,
            "maximum": 20
          },
          "bathroomsMax": {
            "title": "Max Bathrooms",
            "type": "integer",
            "description": "Maximum number of bathrooms.",
            "minimum": 0,
            "maximum": 20
          },
          "parkingMin": {
            "title": "Min Parking Spaces",
            "type": "integer",
            "description": "Minimum number of parking spaces.",
            "minimum": 0,
            "maximum": 20
          },
          "areaMin": {
            "title": "Min Usable Area (m²)",
            "type": "integer",
            "description": "Minimum usable area in square meters.",
            "minimum": 0,
            "maximum": 100000
          },
          "areaMax": {
            "title": "Max Usable Area (m²)",
            "type": "integer",
            "description": "Maximum usable area in square meters.",
            "minimum": 0,
            "maximum": 100000
          },
          "amenities": {
            "title": "Amenities",
            "type": "array",
            "description": "Optional amenity codes the listing must have, for example POOL, GYM, ELEVATOR, BARBECUE_GRILL, or PETS_ALLOWED.",
            "editor": "stringList",
            "items": {
              "type": "string"
            }
          },
          "listingUrls": {
            "title": "Listing URLs or IDs",
            "type": "array",
            "description": "VivaReal listing URLs or numeric IDs to fetch (mode=byUrls). Example: https://www.vivareal.com.br/imovel/2918839249/",
            "editor": "stringList",
            "items": {
              "type": "string"
            }
          },
          "maxItems": {
            "title": "Max Items",
            "type": "integer",
            "description": "Maximum number of listings to return.",
            "minimum": 1,
            "maximum": 1000,
            "default": 50,
            "prefill": 3
          }
        },
        "required": [
          "mode"
        ]
      },
      "output": {
        "actorOutputSchemaVersion": 1,
        "title": "VivaReal Brazil Real Estate Listings by City & Price Output",
        "description": "One record per VivaReal Brazil listing, with BRL price, condo fee, IPTU, areas, rooms, address and coordinates, amenities, photos, advertiser contacts, and listing URL.",
        "properties": {
          "listings": {
            "type": "string",
            "title": "VivaReal Brazil listings",
            "description": "Dataset containing all scraped property listings from VivaReal Brazil.",
            "template": "{{links.apiDefaultDatasetUrl}}/items"
          }
        }
      },
      "storages": {
        "dataset": {
          "actorSpecification": 1,
          "views": {
            "overview": {
              "title": "Properties",
              "transformation": {
                "fields": [
                  "title",
                  "price",
                  "currency",
                  "condoFee",
                  "area",
                  "totalArea",
                  "bedrooms",
                  "bathrooms",
                  "parkingSpaces",
                  "city",
                  "neighborhood",
                  "propertyType",
                  "listingUrl"
                ]
              },
              "display": {
                "component": "table",
                "properties": {}
              }
            }
          }
        }
      },
      "environmentVariables": {}
    },
    "buildNumber": "1.1.1",
    "imageDigest": "d0cbcdc5f910c38cbf39aa191d0fac92454322b5532c23a2ac007729f4a2de8c",
    "actVersion": {
      "sourceType": "SOURCE_FILES",
      "buildTag": "latest",
      "versionNumber": "1.1"
    },
    "usage": {
      "ACTOR_COMPUTE_UNITS": 0.013475555555555555
    }
  }
}