# VivaReal Search API Documentation Scrappa's `GET /api/vivareal/search` returns Brazilian property listings for rent (`business=RENTAL`) or sale (`business=SALE`) from ZAP Imoveis or VivaReal as structured JSON. ## What you get One request returns up to 30 listings plus `total`. Each listing has `prices` (price, condo fee, IPTU, total monthly rent), `usable_area_m2`, rooms, a full `address` with coordinates, H3 cells and nearby points of interest, `amenities`, `images` (1024x768) and the `advertiser` identity. Areas and room counts the portal does not publish are `null`, never 0. ## Location Use `location_id` from the location-autocomplete endpoint. The portal ignores city names, so there is no city filter. ## Paging and the 1500 row window Each query reaches at most 1500 rows (`rows` x `page`). A request past that returns a 422 `window_limit` before any upstream call, and nothing is charged. To reach more listings, split the query by location, price band or area band and de-duplicate by `id`. ## Totals and sorting `total` is approximate and drifts while you page (`total_is_approximate` is always true). Do not use it as a cursor. `BIGGEST_PRICE` and `BIGGEST_AREA` page stably. `LOWEST_PRICE` and `MOST_RELEVANT` pages can overlap, so de-duplicate by `id`. ## Filters that are rejected Names the portal silently ignores (`addressCity`, `bedroomsMin`, `usableAreaMin`) and unknown names return 422 `blocked_filter` instead of a quiet wrong answer. Unit types, usage types and sort values are checked before the call. Lists are comma-separated, for example `bedrooms=2,3`. ## What is not returned Broker phone numbers and WhatsApp numbers are never returned. A valid answer is billed, including an empty page. Failures never consume credits. - **Documentation:** [https://scrappa.co/docs/vivareal-api/vivareal_search](https://scrappa.co/docs/vivareal-api/vivareal_search) - **API group:** VivaReal & ZAP Imoveis API - **Endpoint:** `GET https://scrappa.co/api/vivareal/search` ## Authentication Send your Scrappa API key in the `X-API-KEY` request header. Paid endpoints also support accountless x402 payments when called without an API key. ## Parameters | Parameter | Type | Required | Description | | --- | --- | --- | --- | | `portal` | string | No | ZAP (default) for ZAP Imoveis or VIVAREAL for VivaReal. Both use the same fields and filters. | | `business` | string | Yes | RENTAL (aluguel) or SALE (venda). | | `location_id` | string | No | Location id from location-autocomplete, for example BR>Sao Paulo>NULL>Sao Paulo>Zona Oeste>Pinheiros. The only working location filter. | | `listing_type` | string | No | USED (default), DEVELOPMENT or USED,DEVELOPMENT. | | `q` | string | No | Free text filter. | | `price_min` | integer | No | Minimum advertised price in BRL. | | `price_max` | integer | No | Maximum advertised price in BRL. | | `rental_total_min` | integer | No | Minimum monthly rent including condo fee and IPTU. | | `rental_total_max` | integer | No | Maximum monthly rent including condo fee and IPTU. | | `condo_fee_min` | integer | No | Minimum monthly condo fee in BRL. | | `condo_fee_max` | integer | No | Maximum monthly condo fee in BRL. | | `bedrooms` | string | No | Bedroom counts, comma-separated, for example 2,3. | | `bathrooms` | string | No | Bathroom counts, comma-separated. | | `suites` | string | No | Suite counts, comma-separated. | | `parking_spaces` | string | No | Parking space counts, comma-separated. | | `area_min` | integer | No | Minimum usable area in square metres. | | `area_max` | integer | No | Maximum usable area in square metres. | | `unit_types` | string | No | Comma-separated: APARTMENT, HOME, CONDOMINIUM, COMMERCIAL_PROPERTY, PARKING_SPACE, BUILDING, RESIDENTIAL_ALLOTMENT_LAND, FARM, PENTHOUSE, FLAT, KITNET, TWO_STORY_HOUSE, COMMERCIAL_BUILDING, OFFICE, BUSINESS. | | `unit_sub_types` | string | No | Comma-separated: PENTHOUSE, FLAT, LOFT, STUDIO, KITNET, DUPLEX, TRIPLEX, TWO_STORY_HOUSE, SINGLE_STOREY_HOUSE. | | `usage_types` | string | No | RESIDENTIAL or COMMERCIAL, comma-separated. | | `amenities` | string | No | Comma-separated amenity codes such as POOL, GYM, ELEVATOR. The count endpoint lists the codes with counts. | | `advertiser_id` | string | No | Restrict to one advertiser uuid. | | `sort` | string | No | MOST_RELEVANT (default), BIGGEST_PRICE, BIGGEST_AREA or LOWEST_PRICE. | | `rows` | integer | No | Listings per page, 1-30 (default 30). | | `page` | integer | No | Result page, 1-based. rows x page may not pass 1500. | ## Example request ```bash #!/bin/bash curl -X GET \ -H "x-api-key: YOUR_API_KEY_HERE" \ "https://scrappa.co/api/vivareal/search?portal=ZAP&business=RENTAL&location_id=BR%3ESao+Paulo%3ENULL%3ESao+Paulo%3EZona+Oeste%3EPinheiros&bedrooms=2&sort=BIGGEST_PRICE&rows=5" ``` ## Example response ```json { "success": true, "total": 4255, "total_is_approximate": true, "page": 1, "rows": 5, "returned": 1, "total_pages": 300, "window_limit": 1500, "applied_filters": { "portal": "ZAP", "business": "RENTAL", "listing_type": "USED", "sort": "BIGGEST_PRICE", "location_id": "BR>Sao Paulo>NULL>Sao Paulo>Zona Oeste>Pinheiros", "bedrooms": [ 2 ] }, "listings": [ { "id": "2814207417", "external_id": "9015A005WH", "title": "Apartamento com 2 quartos a venda e para alugar em Pinheiros, Sao Paulo", "description": "Unidade disponivel em um dos empreendimentos mais sofisticados de Sao Paulo.", "listing_type": "USED", "property_type": "UNIT", "unit_types": [ "APARTMENT" ], "unit_sub_types": [], "usage_types": [ "RESIDENTIAL" ], "construction_status": null, "publication_type": "STANDARD", "show_price": true, "accepts_exchange": false, "prices": [ { "business": "RENTAL", "price": 12800, "condo_fee": 2060, "iptu": null, "iptu_period": "YEARLY", "rent_total": 14860, "rent_period": "MONTHLY" }, { "business": "SALE", "price": 2650000, "condo_fee": 2060, "iptu": null, "iptu_period": "YEARLY", "rent_total": null, "rent_period": null } ], "usable_area_m2": 85, "total_area_m2": 85, "bedrooms": 2, "bathrooms": 2, "suites": 2, "parking_spaces": 2, "floors": [], "unit_floor": null, "address": { "street": null, "street_number": null, "neighborhood": "Pinheiros", "zone": "Zona Oeste", "city": "Sao Paulo", "state": "Sao Paulo", "state_code": "SP", "zip_code": "05414020", "full_address": "Rua Francisco Leitao Pinheiros Sao Paulo SP", "location_id": "BR>Sao Paulo>NULL>Sao Paulo>Zona Oeste>Pinheiros", "lat": -23.561, "lon": -46.681, "approximate": true, "radius_m": 250, "precision": "GEOMETRIC_CENTER", "h3": [ { "index": "89a8100eab3ffff", "resolution": 9 } ], "pois": [ "BS:Rua Henrique Schaumann, 462" ] }, "amenities": [], "images": [ { "id": "439a18da4c6f6047a797e444ec0520c0", "type": "IMAGE", "url": "https://resizedimgs.zapimoveis.com.br/img/vr-listing/439a18da4c6f6047a797e444ec0520c0/photo.jpg?action=fit-in&dimension=1024x768", "width": 1024, "height": 768 } ], "advertiser": { "id": "cef4b87e-6256-8bb2-b798-cf23e10cd883", "legacy_id": 810901, "legacy_zap_id": null, "name": "Example Imoveis Ltda", "logo_url": "https://resizedimgs.zapimoveis.com.br/img/vr-listing/718513a5c1a190eb20c1107deb8b40dd/logo.jpg?action=fit-in&dimension=200x200", "license_number": null, "tier": "diamond", "trust_score": null, "created_at": "2023-07-26T21:29:17Z", "show_address": false, "minisite": null }, "url": null, "created_at": "2025-06-14T19:02:35.799Z", "updated_at": "2026-09-24T06:27:41.926Z", "stamps": [], "status": "ACTIVE" } ], "meta": { "billable": true, "endpoint_family": "search", "portal": "ZAP", "attempts": 1 } } ``` ## Frequently asked questions ### Why can I only reach 1500 listings per query? The portal serves a window of 1500 rows per query. Split the query by location, price band or area band and de-duplicate by listing id. ### Is the total exact? No. The portal total is a live figure that drifts while you page. Treat it as approximate. ### Is this the official VivaReal or ZAP API? No. Scrappa is an independent service and is not affiliated with VivaReal, ZAP Imoveis or their owners. Neither portal publishes a developer API. ### Are failed requests charged? A valid answer is billed, including an empty page. Failures never consume credits. ## Related endpoints - [Location Autocomplete](https://scrappa.co/docs/vivareal-api/vivareal_location_autocomplete) - [Property Detail](https://scrappa.co/docs/vivareal-api/vivareal_listing) - [Property Count](https://scrappa.co/docs/vivareal-api/vivareal_count) ## More Scrappa resources - [API documentation](https://scrappa.co/docs) - [Full LLM-readable API reference](https://scrappa.co/llms-full.txt) - [OpenAPI specification](https://scrappa.co/docs/api.json) - [Pricing](https://scrappa.co/pricing)