# Vivareal — Wrapped API

> **You are on:** `https://api.paywithlocus.com/api` | [llms.txt](https://paywithlocus.com/llms.txt) | [docs](https://docs.paywithlocus.com)
>
> Locus runs on multiple environments -- make sure every URL you call matches your expected environment.
> | Environment | Landing | API | Docs |
> |---|---|---|---|
> | Production | paywithlocus.com | api.paywithlocus.com | docs.paywithlocus.com |
> | Beta | beta.paywithlocus.com | api.beta.paywithlocus.com | docs.paywithlocus.com |
> | Stage | stage.paywithlocus.com | api.stage.paywithlocus.com | docs.paywithlocus.com |
>
> If the API URL above doesn't match your expected environment, re-fetch this file from the correct domain.

> Search for properties across Brazil's real estate marketplace and access detailed listings with photos, amenities, contact information, and agency portfolios. Discover homes by location, browse available property types, and connect directly with real estate advertisers.

**Category:** Real Estate | **Website:** [vivareal.com.br/](https://vivareal.com.br/) | **Docs:** [parse.bot/marketplace/3a2aa599-4178-4a3b-be27-f0911f573310/vivareal-com-br-api](https://parse.bot/marketplace/3a2aa599-4178-4a3b-be27-f0911f573310/vivareal-com-br-api)

Pay-per-use API proxy. Each call is automatically billed to your wallet in USDC.

## Access

**Base URL:** `https://api.paywithlocus.com/api/wrapped/parse-vivareal-com-br-api-3a2aa599/`
**Auth:** `Authorization: Bearer <LOCUS_API_KEY>`

## Endpoints

### get_advertiser_listings

List all active property listings from a specific real estate agency or advertiser. Returns paginated results with total_count. The advertiser_id comes from search_listings or get_listing_details results.

**Estimated cost:** Metered

| Field | Type | Required | Description |
|-------|------|----------|-------------|
| `advertiser_id` | string | Yes | Advertiser/agency ID from search_listings or get_listing_details results. |
| `page` | integer | No | Page number for pagination (1-based). |
| `size` | integer | No | Results per page. |

```bash
curl -X POST https://api.paywithlocus.com/api/wrapped/parse-vivareal-com-br-api-3a2aa599/get_advertiser_listings \
  -H "Authorization: Bearer YOUR_LOCUS_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"advertiser_id":"<string>","page":"<integer>","size":"<integer>"}'
```

### get_listing_details

Retrieve full details for a single property listing by its unique ID. Returns a flattened listing object with all property details, pricing, amenities, media URLs, and advertiser info.

**Estimated cost:** Metered

| Field | Type | Required | Description |
|-------|------|----------|-------------|
| `listing_id` | string | Yes | Unique listing ID from search_listings results. |

```bash
curl -X POST https://api.paywithlocus.com/api/wrapped/parse-vivareal-com-br-api-3a2aa599/get_listing_details \
  -H "Authorization: Bearer YOUR_LOCUS_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"listing_id":"<string>"}'
```

### get_listing_photos

Retrieve all photo URLs for a specific property listing, filtered to IMAGE type media only. Returns photo URLs, count, and the listing_id.

**Estimated cost:** Metered

| Field | Type | Required | Description |
|-------|------|----------|-------------|
| `listing_id` | string | Yes | Unique listing ID from search_listings results. |

```bash
curl -X POST https://api.paywithlocus.com/api/wrapped/parse-vivareal-com-br-api-3a2aa599/get_listing_photos \
  -H "Authorization: Bearer YOUR_LOCUS_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"listing_id":"<string>"}'
```

### list_property_types

Retrieve the full list of supported property types with their API codes and live listing counts, grouped by category (Residencial/Comercial). The code field can be used as the property_type filter in search_listings. Results are sorted by count descending.

**Estimated cost:** Metered

_No parameters required._

```bash
curl -X POST https://api.paywithlocus.com/api/wrapped/parse-vivareal-com-br-api-3a2aa599/list_property_types \
  -H "Authorization: Bearer YOUR_LOCUS_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{}'
```

### search_by_location_text

Autocomplete location search terms (neighborhoods, cities, states) based on a text query. Returns location suggestions with locationId values usable as the location_id filter in search_listings. Each result includes category, address with locationId, city, state, neighborhood, and a relative URL path.

**Estimated cost:** Metered

| Field | Type | Required | Description |
|-------|------|----------|-------------|
| `query` | string | Yes | Location search text (e.g. 'Pinheiros', 'Copacabana'). |

```bash
curl -X POST https://api.paywithlocus.com/api/wrapped/parse-vivareal-com-br-api-3a2aa599/search_by_location_text \
  -H "Authorization: Bearer YOUR_LOCUS_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"query":"<string>"}'
```

### search_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.

**Estimated cost:** Metered

| Field | Type | Required | Description |
|-------|------|----------|-------------|
| `bathrooms` | integer | No | Minimum number of bathrooms. |
| `bedrooms` | integer | No | Minimum number of bedrooms. |
| `business` | string | No | Transaction type. |
| `city` | string | No | City name to filter by (e.g. 'São Paulo'). |
| `location_id` | string | No | Location ID from search_by_location_text results (e.g. 'BR>Sao Paulo>NULL>Sao Paulo>Zona Oeste>Pinheiros'). |
| `max_area` | integer | No | Maximum usable area in m². |
| `max_price` | integer | No | Maximum price in BRL. |
| `min_area` | integer | No | Minimum usable area in m². |
| `min_price` | integer | No | Minimum price in BRL. |
| `neighborhood` | string | No | Neighborhood name to filter by. |
| `page` | integer | No | Page number for pagination (1-based). |
| `parking` | integer | No | Minimum number of parking spaces. |
| `property_type` | string | No | Unit type code from list_property_types. |
| `size` | integer | No | Results per page. |
| `state` | string | No | State name to filter by (e.g. 'São Paulo'). |

```bash
curl -X POST https://api.paywithlocus.com/api/wrapped/parse-vivareal-com-br-api-3a2aa599/search_listings \
  -H "Authorization: Bearer YOUR_LOCUS_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"bathrooms":"<integer>","bedrooms":"<integer>","business":"<string>","city":"<string>","location_id":"<string>","max_area":"<integer>","max_price":"<integer>","min_area":"<integer>","min_price":"<integer>","neighborhood":"<string>","page":"<integer>","parking":"<integer>","property_type":"<string>","size":"<integer>","state":"<string>"}'
```