> ## Documentation Index
> Fetch the complete documentation index at: https://docs.brightplace.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# search_listings

> Search apartment listings with objective filters.

`search_listings` searches apartment listings through brightplace using
objective renter criteria.

## When to use it

Use `search_listings` when a renter asks for apartments matching objective
criteria such as price, location, bedrooms, bathrooms, amenities, or move-in
timing.

Do not use it for protected-class or demographic steering requests. Those
requests return `FAIR_HOUSING_VIOLATION`.

## Input

```json theme={null}
{
  "query": "rooftop pool near transit",
  "filters": {
    "locations": [{ "city": "brooklyn", "state": "ny" }],
    "names": ["greystar"],
    "beds": 1,
    "baths": 1,
    "minPrice": 2500,
    "maxPrice": 4500
  },
  "limit": 20
}
```

| Field               | Type    | Required | Notes                                                          |
| ------------------- | ------- | -------- | -------------------------------------------------------------- |
| `query`             | string  | No       | Semantic search text. Empty strings are treated as omitted.    |
| `filters.locations` | array   | No       | City/state filters. Use lowercase city and two-letter state.   |
| `filters.names`     | array   | No       | Property manager brands or specific building names. See below. |
| `filters.beds`      | number  | No       | Exact bedroom count.                                           |
| `filters.baths`     | number  | No       | Minimum bathroom count.                                        |
| `filters.minPrice`  | number  | No       | Minimum monthly rent.                                          |
| `filters.maxPrice`  | number  | No       | Maximum monthly rent.                                          |
| `limit`             | integer | No       | Defaults to 20. Maximum 50.                                    |

Filter-only searches are allowed. When `query` is omitted, brightplace ranks
results from the objective filters provided by the renter.

### Searching by manager or building name

Each entry in `filters.names` is matched case-insensitively as a substring of
both the property manager's name and the building's name, so you can pass a
renter's phrasing without deciding which one they meant: `["greystar"]` reaches
`Greystar Real Estate Partners`, and `["roosevelt collection"]` reaches
`Roosevelt Collection Lofts`. Pass only the distinctive part of the name, not
`"greystar apartments"`. Multiple entries widen the search to any of them, and
the filter combines with location and price as an AND. An empty result means
brightplace holds no inventory under that name.

## Output

The tool returns `ListingSummary[]`.

```json theme={null}
[
  {
    "listing_id": "listing-record-id",
    "unit_id": "unit-id",
    "property_name": "Example Apartments",
    "unit_name": "Apt 5B",
    "latitude": 40.7128,
    "longitude": -74.006,
    "beds": 1,
    "baths": 1,
    "sqft": 720,
    "rent": 3400,
    "concessions": ["1 month free on select lease terms"],
    "fees": [
      {
        "name": "Application fee",
        "amount": 75,
        "frequency": "one_time"
      }
    ],
    "available_at": "2026-07-01",
    "primary_photo_url": "https://example.com/photo.jpg"
  }
]
```

`listing_id` is the listing snapshot id to pass into `get_listing`,
`get_tour_availability`, and `book_tour`.