# VivaReal Price Insights API Documentation

Scrappa's `GET /api/vivareal/price-insights` returns market statistics for one location: `main_location` with the number of properties, average price, average area, average price per m2 and price brackets with counts, and `top_locations` with nearby areas.

City, state, business type, unit type, latitude, longitude and location id are all required. The portal answers an incomplete set with an empty body, which this API reports as 404 `no_data` and does not bill. Take the values from location-autocomplete and keep the accents: an unknown spelling answers 404 `no_data`. Leave neighborhood out for city-level insights. A valid answer is billed, including an empty page. Failures never consume credits.

- **Documentation:** [https://scrappa.co/docs/vivareal-api/vivareal_price_insights](https://scrappa.co/docs/vivareal-api/vivareal_price_insights)
- **API group:** VivaReal & ZAP Imoveis API
- **Endpoint:** `GET https://scrappa.co/api/vivareal/price-insights`

## 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. |
| `city` | string | Yes | City, spelled with accents as location-autocomplete returns it, for example São Paulo. |
| `state` | string | Yes | State, spelled with accents as location-autocomplete returns it, for example São Paulo. |
| `neighborhood` | string | No | Neighbourhood, for example Pinheiros. |
| `business_type` | string | Yes | RENTAL or SALE. |
| `unit_type` | string | Yes | Unit type such as APARTMENT or HOME. |
| `latitude` | number | Yes | Latitude of the location. |
| `longitude` | number | Yes | Longitude of the location. |
| `location_id` | string | Yes | Location id from location-autocomplete. |

## Example request

```bash
#!/bin/bash

curl -X GET \
    -H "x-api-key: YOUR_API_KEY_HERE" \
    "https://scrappa.co/api/vivareal/price-insights?portal=ZAP&city=S%C3%A3o+Paulo&state=S%C3%A3o+Paulo&neighborhood=Pinheiros&business_type=RENTAL&unit_type=APARTMENT&latitude=-23.563579&longitude=-46.691607&location_id=BR%3ESao+Paulo%3ENULL%3ESao+Paulo%3EZona+Oeste%3EPinheiros"
```

## Example response

```json
{
    "success": true,
    "main_location": {
        "location": {
            "name": "Pinheiros",
            "stats": {
                "total_properties": 4255,
                "avg_total_price": 5001,
                "avg_total_area": 50,
                "avg_sqm": 100
            },
            "price_ranges": [
                {
                    "key": "De R$ 1 mil a R$ 2,5 mil",
                    "doc_count": 160
                }
            ]
        }
    },
    "top_locations": [],
    "meta": {
        "billable": true,
        "endpoint_family": "price-insights",
        "portal": "ZAP",
        "attempts": 1
    }
}
```

## Frequently asked questions

### 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)

## 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)