vivareal.com.br APIvivareal.com.br ↗
Access property listings, photos, advertiser portfolios, and location search across Brazil's vivareal.com.br marketplace via a structured REST API.
curl -X GET 'https://api.parse.bot/scraper/42411035-2f85-416e-9114-8c345e206ca3/search_listings?city=S%C3%A3o+Paulo&page=1&size=2&business=SALE&location_id=BR%3ESao+Paulo%3ENULL%3ESao+Paulo' \ -H 'X-API-Key: $PARSE_API_KEY'
Search for property listings (houses, apartments, etc.) for sale or rent across Brazil. Supports extensive filters for location, price, area, and property features. Returns paginated results.
| Param | Type | Description |
|---|---|---|
| city | string | City name to filter by (e.g. 'São Paulo'). |
| page | integer | Page number for pagination. |
| size | integer | Results per page. |
| state | string | State name to filter by (e.g. 'São Paulo'). |
| parking | integer | Minimum number of parking spaces. |
| bedrooms | integer | Minimum number of bedrooms. |
| business | string | Transaction type: 'SALE' or 'RENTAL'. |
| max_area | integer | Maximum usable area in m². |
| min_area | integer | Minimum usable area in m². |
| bathrooms | integer | Minimum number of bathrooms. |
| max_price | integer | Maximum price in BRL. |
| min_price | integer | Minimum price in BRL. |
| location_id | string | Location ID from search_by_location_text results (e.g. 'BR>Sao Paulo>NULL>Sao Paulo>Zona Oeste>Pinheiros'). |
| neighborhood | string | Neighborhood name to filter by. |
| property_type | string | Unit type code from list_property_types (e.g. 'APARTMENT', 'HOME', 'CONDOMINIUM', 'PENTHOUSE', 'FLAT', 'OFFICE'). |
{
"type": "object",
"fields": {
"search": "object containing result.listings array and totalCount integer"
},
"sample": {
"data": {
"search": {
"result": {
"listings": [
{
"medias": [
{
"url": "https://resizedimgs.vivareal.com/img/vr-listing/ac098aef539bd2325652510d8033f6fe/{description}.jpg",
"type": "IMAGE"
}
],
"account": {
"id": "5ac20bd6-4594-fa73-e742-ca5660f81a42",
"name": "Spaco Consultoria Imobiliaria Ltda."
},
"listing": {
"id": "2850721703",
"title": "Imóvel para venda tem 45 metros quadrados",
"status": "ACTIVE",
"address": {
"city": "São Paulo",
"state": "São Paulo",
"neighborhood": "Vila Mascote"
},
"bedrooms": [
1
],
"amenities": [
"KITCHEN_CABINETS",
"PARTY_HALL"
],
"bathrooms": [
1
],
"listingType": "USED",
"usableAreas": [
"45"
],
"pricingInfos": [
{
"price": "399000",
"businessType": "SALE",
"monthlyCondoFee": "800"
}
],
"parkingSpaces": [
1
]
}
}
]
},
"totalCount": 1384159
}
},
"status": "success"
}
}About the vivareal.com.br API
The Vivareal API exposes 6 endpoints for querying Brazil's vivareal.com.br real estate marketplace, covering residential and commercial properties for sale or rent. With search_listings you can filter by city, state, bedrooms, parking, area, and transaction type, while get_listing_details returns full property data including amenities, pricing, address, and advertiser contact information in a single call.
Search and Filter Listings
search_listings is the primary discovery endpoint. It accepts filters for city, state, bedrooms, parking, max_area, and business (either SALE or RENTAL). Results are paginated via page and size parameters. The response wraps a search object containing a result.listings array and a totalCount integer, so you can determine how many pages to fetch. To narrow by neighborhood or sub-district, first call search_by_location_text with a text query — it returns locationId values you can pass as the location_id filter, along with city, state, and neighborhood fields for display.
Listing Details, Photos, and Property Types
get_listing_details accepts a listing_id (returned inside any search_listings result) and returns three top-level objects: listing (id, title, description, address, bedrooms, bathrooms, pricingInfos, amenities, and advertiser contact), account (advertiser name, logoUrl, licenseNumber), and medias (an array of objects with url and type). If you only need images, get_listing_photos filters the media to IMAGE type only and returns a flat photos array, the listing_id, and a photo_count integer — convenient for thumbnail grids without parsing the full media array.
Advertiser Portfolios and Property Type Reference
get_advertiser_listings takes an advertiser_id (available from both search and detail responses) and returns all active listings from that agency, paginated the same way as search_listings. This makes it straightforward to build agency-level property pages. list_property_types requires no inputs and returns every supported type — e.g. APARTMENT, HOME — with a Portuguese display name, a category of either Residencial or Comercial, and a live count of current sale listings. The code field maps directly to the property_type filter in search_listings.
- Build a Brazil property search engine filtered by city, state, and bedroom count using
search_listings. - Aggregate listing photos for a gallery view by calling
get_listing_photosfor each result and reading thephotosarray. - Display full agency portfolios by fetching all listings for an
advertiser_idviaget_advertiser_listings. - Implement neighborhood autocomplete in a search form using
search_by_location_textto resolvelocationIdvalues. - Render a property detail page with price, amenities, and advertiser logo using fields from
get_listing_details. - Build a property type selector by calling
list_property_typesto show live listing counts per category. - Compare rental versus sale inventory across Brazilian cities by toggling the
businessparameter insearch_listings.
| Tier | Price | Credits/month | Rate limit |
|---|---|---|---|
| Free | $0/mo | 100 | 5 req/min |
| Hobby | $30/mo | 1,000 | 20 req/min |
| Developer | $100/mo | 5,000 | 250 req/min |
One credit = one API call regardless of which marketplace API you call. Exceeding the rate limit returns a 429 response. Authenticate with the X-API-Key header.
Does Vivareal have an official public developer API?+
What does `get_listing_details` return beyond what appears in search results?+
get_listing_details returns the full listing object including description, amenities, and pricingInfos, the account object with advertiser name, logoUrl, and licenseNumber, and a medias array with url and type for each media item. Search results contain summary data; the detail endpoint is the only way to retrieve the full amenities list and advertiser contact fields.Can I filter `search_listings` by neighborhood directly?+
neighborhood string parameter on search_listings. The supported path is to call search_by_location_text with a neighborhood name (e.g. 'Pinheiros'), take the locationId from the response, and pass it as the location_id filter in search_listings.Does the API cover sold or off-market properties, or price history?+
pricingInfos, but does not include sold transactions, off-market records, or historical price changes. You can fork this API on Parse and revise it to add an endpoint targeting that data if vivareal surfaces it.Is there a minimum area filter, or only maximum area?+
search_listings exposes max_area for an upper bound on usable area in m², but there is no min_area parameter in the current spec. The API covers the maximum-area filter only. You can fork this API on Parse and revise it to add a minimum area parameter if that filter is needed.