Vivareal APIvivareal.com.br ↗
Access property listings, photos, advertiser portfolios, and location search across Brazil's vivareal.com.br marketplace via a structured REST API.
What is the Vivareal 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.
curl -X GET 'https://api.parse.bot/scraper/42411035-2f85-416e-9114-8c345e206ca3/search_listings?city=S%C3%A3o+Paulo&page=1&size=3&state=S%C3%A3o+Paulo&parking=1&bedrooms=2&business=SALE&max_area=200&min_area=50&bathrooms=1&max_price=500000&min_price=100000&location_id=BR%3ESao+Paulo%3ENULL%3ESao+Paulo%3EZona+Oeste%3EPinheiros&neighborhood=Pinheiros&property_type=APARTMENT' \ -H 'X-API-Key: $PARSE_API_KEY'
Typed, relational, agent-ready
A generated client with real types, enums, and the links between objects — the structure a flat JSON response can't carry. Autocompletes in your editor and reads cleanly to coding agents.
- Fully typed · autocompletes
- Objects link to objects
- Typed errors & pagination
Typed Python client. Set up the SDK in your uv project, then pull this API’s typed client:
uv add parse-sdk uv run parse init uv run parse add --marketplace vivareal-com-br-api
uv run parse add --marketplace pulls a pinned snapshot of this canonical API — it won’t change underneath you. To customize it, subscribe and swap to your own copy.
"""VivaReal Property Listings API - Walkthrough
Search Brazilian real estate listings, browse by location, and drill into property details.
"""
from parse_apis.vivareal_property_listings_api import (
VivaReal, BusinessType, PropertyType, ListingNotFound
)
client = VivaReal()
# Search apartments for sale in São Paulo, capped at 3 results
for listing in client.listings.search(
business=BusinessType.SALE,
property_type=PropertyType.APARTMENT,
city="São Paulo",
bedrooms=2,
limit=3,
):
print(listing.title, listing.address.city, listing.pricing_infos[0].price)
# Take one listing and get its photo URLs
listing = client.listings.search(
business=BusinessType.SALE, neighborhood="Pinheiros", limit=1
).first()
if listing:
photos = listing.photos()
print(f"{photos.photo_count} photos for listing {photos.listing_id}")
# Autocomplete a location search to find location IDs
for loc in client.locationsuggestions.search(query="Copacabana", limit=3):
print(loc.category, loc.location_id)
# List property types to see what's available
for pt in client.propertytypeinfos.list(limit=5):
print(pt.code, pt.name, pt.count)
# Browse an advertiser's listings using constructible Advertiser
if listing:
advertiser = client.advertiser(id=listing.account_id)
for adv_listing in advertiser.listings(limit=2):
print(adv_listing.title, adv_listing.account_name)
# Handle a not-found listing gracefully
try:
detail = client.listings.get(id="nonexistent_id_999")
print(detail.title)
except ListingNotFound as exc:
print(f"Listing not found: {exc.listing_id}")
print("exercised: listings.search / listings.get / listing.photos / locationsuggestions.search / propertytypeinfos.list / advertiser.listings")
Full-text search over Brazilian property listings (houses, apartments, etc.) for sale or rent. Supports location, price, area, and feature filters. Returns paginated results with total_count. Each listing item includes id, title, address, pricing, amenities, account info, and media references. Paginates via integer page counter.
| Param | Type | Description |
|---|---|---|
| city | string | City name to filter by (e.g. 'São Paulo'). |
| page | integer | Page number for pagination (1-based). |
| 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. |
| 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. |
{
"type": "object",
"fields": {
"listings": "array of flattened listing objects with id, title, address, bedrooms, bathrooms, pricingInfos, amenities, account_id, account_name, medias",
"total_count": "integer total number of matching listings"
},
"sample": {
"data": {
"listings": [
{
"id": "2811942748",
"title": "Casa 4/4 no Terras Alphaville",
"medias": [
{
"url": "https://resizedimgs.vivareal.com/img/vr-listing/2eae14ce.jpg",
"type": "IMAGE"
}
],
"status": "ACTIVE",
"address": {
"city": "Camaçari",
"state": "Bahia",
"street": "Rodovia da BA-531",
"locationId": "BR>Bahia>NULL>Camacari>Barrios>Jardim Limoeiro",
"neighborhood": "Jardim Limoeiro",
"stateAcronym": "BA"
},
"bedrooms": [
4
],
"amenities": [
"TENNIS_COURT",
"GARDEN"
],
"bathrooms": [
5
],
"account_id": "54e08637-2510-d8a3-ddd4-f1c01d7a28c9",
"listingType": "USED",
"usableAreas": [
"217"
],
"account_name": "Corretora Gislene Moreira",
"pricingInfos": [
{
"price": "1230000",
"businessType": "SALE"
}
],
"parkingSpaces": [
0
],
"account_logo_url": "",
"account_license_number": "31346-F-BA"
}
],
"total_count": 5155020
},
"status": "success"
}
}About the Vivareal API
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.
The Vivareal API is a managed, monitored endpoint for vivareal.com.br — not a raw scraper you maintain. Every endpoint is automatically health-checked on a schedule, and when vivareal.com.br changes and a check fails, the API is automatically queued for repair and re-verified. It is built to keep working as the site underneath it changes.
This isn't an official vivareal.com.br API — it's an independent, maintained REST wrapper over public data. Where the source has no official API (or only a limited one), Parse gives you a stable contract over a source that never promised one, and keeps it current. Need a new endpoint or field? You can revise it yourself in plain English and the agent rebuilds it against the live site in minutes — contributing the change back to the shared API is free.
Will this API break when the source site changes?+
Is this an official API from the source site?+
Can I fix or extend this API myself if I need a new endpoint or field?+
What happens if I call an endpoint that has an issue?+
- 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 | 100 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.