# Viva Real Search ## Overview | Property | Value | |----------|-------| | **Status** | active | | **Method** | `GET` | | **Endpoint** | `/v2/vivareal/search` | | **Base URL** | `https://api.piloterr.com` | | **Credit Cost** | 1 credit per call | | **Documentation** | https://www.piloterr.com/library/vivareal-search | ## Description Search Viva Real by city and operation, sale or rent. Page with pagina. Development cards and 'from' prices are left out. ## Authentication - **Key Name:** `x-api-key` - **Location:** HTTP Header - **Get an API key:** https://app.piloterr.com/register ## Example Request ```bash curl --location --request GET 'https://api.piloterr.com/v2/vivareal/search' \ --header 'Content-Type: application/json' \ --header 'x-api-key: YOUR_API_KEY' ``` ## Example Response ### São Paulo sale, Tatuapé apartment 2910482320 ```json { "results": [ { "id": "2910482320", "url": "https://www.vivareal.com.br/imovel/apartamento-4-quartos-tatuape-zona-leste-sao-paulo-com-garagem-225m2-venda-RS4250000-id-2910482320/", "area": 225, "city": "São Paulo", "iptu": 1293, "price": 4250000, "title": "Apartamento para comprar com 225 m², 4 quartos, 5 banheiros, 4 vagas em Chácara Califórnia, São Paulo", "address": "Rua Antônio de Lucena, Chácara Califórnia, São Paulo - SP", "bedrooms": 4, "currency": "BRL", "bathrooms": 5, "image_url": "https://resizedimgs.vivareal.com/img/vr-listing/f343296aa94fef7c6d452a62715150c6/apartamento-com-4-quartos-a-venda-225m-no-chacara-california-sao-paulo.webp?action=fit-in&dimension=614x297", "operation": "sale", "state_code": "SP", "condominium": 3072, "neighborhood": "Chácara Califórnia", "price_display": "R$ 4.250.000", "property_type": "apartment", "parking_spaces": 4 } ], "pagination": { "next": "https://www.vivareal.com.br/venda/sp/sao-paulo/?onde=%2CS%C3%A3o+Paulo%2CS%C3%A3o+Paulo%2C%2C%2C%2C%2Ccity%2CBR%3ESao+Paulo%3ENULL%3ESao+Paulo%2C-23.555771%2C-46.639557%2C&pagina=2", "page": 1, "per_page": 30, "total_pages": 27853, "total_results": 835576 } } ``` ## Documentation ## Overview Viva Real sale and rent search on [www.vivareal.com.br](https://www.vivareal.com.br). `query` placeholder is `São Paulo`. `operation` placeholder is `sale`. `property_type` placeholder is `apartment`. `page` placeholder is `2`, sent to Viva Real as `pagina`. `price` is the asking price in BRL. `price_display` is the card text, such as `R$ 4.250.000`. `currency` is `BRL` when a price is present. The response has no struck previous price. Each response is one transaction. New-development cards (`/imoveis-lancamentos/`) and "A partir de" prices are omitted, so `results` can be shorter than `per_page`. Page 1 and page 2 list different homes. A few featured listing ids can appear on both pages. Most ids on page 2 are new. ## Quickstart ``` GET https://api.piloterr.com/v2/vivareal/search?query=S%C3%A3o%20Paulo&operation=sale GET https://api.piloterr.com/v2/vivareal/search?query=S%C3%A3o%20Paulo&operation=sale&page=2 GET https://api.piloterr.com/v2/vivareal/search?query=Rio%20de%20Janeiro,%20RJ&operation=rent GET https://api.piloterr.com/v2/vivareal/search?query=https://www.vivareal.com.br/venda/sp/sao-paulo/ ``` São Paulo sale, page 1, includes listing `2910482320`: Rua Antônio de Lucena, Chácara Califórnia, `R$ 4.250.000`, 225 m², 4 bedrooms. Property URL for that card: ``` https://www.vivareal.com.br/imovel/apartamento-4-quartos-tatuape-zona-leste-sao-paulo-com-garagem-225m2-venda-RS4250000-id-2910482320/ ``` ## Parameters | Parameter | Type | Required | Placeholder | Example | |---|---|---|---|---| | `query` | string | yes | `São Paulo` | `Rio de Janeiro, RJ` | | `operation` | string | no | `sale` | `rent` | | `property_type` | string | no | `apartment` | `house` | | `page` | integer | no | `2` | `2` | A search URL keeps `/venda/` or `/aluguel/`. When `page` stays at 1, a `pagina` value already in that URL is kept. A listing URL returns 400. ## Response fields | Field | Type | Description | |---|---|---| | `results` | array | One object per listing | | `results[].id` | string | Viva Real listing id | | `results[].url` | string | Listing URL under `/imovel/` | | `results[].title` | string | Card title | | `results[].price` | integer | Asking price in BRL | | `results[].price_display` | string | Price as shown, for example `R$ 4.250.000` | | `results[].currency` | string | `BRL` | | `results[].address` | string | Street, neighborhood, and city | | `results[].neighborhood` | string or null | Neighborhood | | `results[].city` | string or null | City | | `results[].state_code` | string or null | State code, such as `SP` | | `results[].area` | integer or null | Area in m² when the card shows one number | | `results[].bedrooms` | integer or null | Bedroom count | | `results[].bathrooms` | integer or null | Bathroom count | | `results[].parking_spaces` | integer or null | Garage spaces | | `results[].property_type` | string or null | `apartment`, `house`, `commercial`, and similar | | `results[].operation` | string | `sale` or `rent` | | `results[].condominium` | integer or null | Condo fee. `0` when the card says isento | | `results[].iptu` | integer or null | IPTU amount | | `results[].image_url` | string or null | Card photo | | `pagination.page` | integer | Current page | | `pagination.per_page` | integer | Viva Real page size, 30 | | `pagination.total_results` | integer | Count shown on the page | | `pagination.total_pages` | integer or null | Page count | | `pagination.next` | string or null | Next Viva Real URL, with `pagina` | ## Main use cases - Scan São Paulo apartments for sale - Collect Rio rentals - Keep the sale price when the card also shows a rent ## Error codes | Code | Meaning | |---|---| | 400 | Missing query, unknown city, bad operation or type, bad domain, or a listing URL | | 401 | Missing API key | | 404 | No listings | | 500 | Fetch or parse failure | ## Related endpoints [Viva Real Property](https://www.piloterr.com/library/vivareal-property)