# Search candidate listings for a dynamic set.

`GET /sets/candidates`

> Wheelhouse Revenue Management API. Web version: https://docs.usewheelhouse.com/rm/reference/rm-get-set-candidates · OpenAPI spec: https://docs.usewheelhouse.com/rm/openapi.yaml · Operation ID: `rmGetSetCandidates` · Tag: Dynamic Sets

Returns market listings near a location, with their trailing-year performance metrics, to choose from when building a dynamic set. Provide either a `lat`/`long`/`radius` (radius in meters) or one or more `market_ids`. Results are ordered nearest-first (each carries a `distance_meters` value) and paginated. Pass the returned `listing_id`s to `POST /sets` to add them as members. Not tied to a set, so no set plan applies.

## Request

`GET https://api.usewheelhouse.com/ss_api/v1/sets/candidates`

Authentication: send your RM API key in the `X-Integration-Api-Key` header (see https://docs.usewheelhouse.com/rm/authentication.md). Read-only keys can call this endpoint.

### Query parameters

| Name | Type | Required | Description |
| --- | --- | --- | --- |
| `lat` | number | no | Latitude of the search center. Must be sent together with long and radius. |
| `long` | number | no | Longitude of the search center. Must be sent together with lat and radius. |
| `radius` | integer | no | Search radius in meters. Must be sent together with lat and long. |
| `market_ids` | array of integer | no | Restrict candidates to these markets. Provide this or lat/long/radius. Send more than one in brackets (`?market_ids[]=12&market_ids[]=34`); a key repeated without brackets keeps only its last value. |
| `min_bedrooms` | integer | no |  |
| `max_bedrooms` | integer | no |  |
| `min_bathrooms` | number | no |  |
| `max_bathrooms` | number | no |  |
| `room_types` | array of string | no | Restrict candidates to these normalized room types. Send more than one in brackets (`?room_types[]=apartment&room_types[]=house`); a key repeated without brackets keeps only its last value. (each item one of: `apartment`, `bnb`, `boat`, `bus`, `cabin`, `camper`, `camping`, `castle`, `holiday_home`, `hostel`, `hotel`, `house`, `houseboat`, `island`, `mill`, `other`, `room`, `shared`, `tower`) |
| `min_bookable_nights_0_365` | integer | no | Minimum bookable nights over the next 365 days. |
| `min_open_occupancy_0_365` | number | no | Minimum forward-looking adjusted occupancy (0–1). |
| `min_open_occupancy_365_0` | number | no | Minimum trailing-year adjusted occupancy (0–1). Defaults to 0.35. (default: `0.35`) |
| `min_bookable_nights_365_0` | integer | no | Minimum trailing-year bookable nights. Defaults to 127. (default: `127`) |
| `per_page` | integer | no | Number of candidates per page. (default: `50`, min: 1, max: 100) |
| `page` | integer | no | Page number to retrieve. |

### Example request

```bash
curl -X GET 'https://api.usewheelhouse.com/ss_api/v1/sets/candidates' \
  -H 'X-Integration-Api-Key: <your RM API key>'
```

Only required parameters and body fields are filled in, with placeholder values. Add the optional ones you need from the lists above; some are required in combination, as their descriptions say.

## Responses

### 200

Array of candidate listings ordered nearest-first.

Body (`application/json`): array of object `candidate_listing_response`

A market listing with trailing-year performance metrics, named per the public [Wheelhouse metrics definitions](https://www.usewheelhouse.com/research-metrics). Metrics with the suffix `_365_0` cover the past 365 days; `_90_0` covers the past 90 days. When returned from a proximity search (`GET /sets/candidates`), `distance_meters` is the distance from the search center.

- `listing_id` (integer, required): The Wheelhouse internal listing ID.
- `title` (string, nullable): The listing title.
- `source` (string, nullable): The channel the listing was sourced from.
- `url` (string, nullable): Public URL of the listing on its channel.
- `thumb_url` (string, nullable): Thumbnail image URL.
- `owner_name` (string, nullable): The listing host/owner name.
- `lat` (number): Latitude of the listing.
- `long` (number): Longitude of the listing.
- `market_id` (integer, nullable): The Wheelhouse internal market ID of the listing.
- `currency` (string, nullable): The ISO-4217 3-letter currency code of the listing's monetary metrics.
- `bedrooms` (integer, nullable): Number of bedrooms.
- `bathrooms` (number, nullable): Number of bathrooms (may be fractional, e.g. 1.5).
- `beds` (integer, nullable): Number of beds.
- `sleeps` (integer, nullable): Maximum number of guests the listing sleeps.
- `guests_included` (integer, nullable): Number of guests included in the base price.
- `room_type` (string, nullable): The room type of the listing.
- `property_type` (string, nullable): The property type of the listing.
- `amenities` (array of string): List of amenities available at the listing.
- `cleaning_fee` (integer, nullable): Cleaning fee amount in the listing's currency.
- `star_rating` (number, nullable): Guest star rating.
- `review_count` (integer, nullable): Number of guest reviews.
- `adr_365_0` (number, nullable): Average Daily Rate — average nightly price over the past 365 days.
- `asking_rate_365_0` (number, nullable): Average nightly asking price over the past 365 days.
- `occupancy_365_0` (number, nullable): Occupancy over the past 365 days.
- `occupancy_adjusted_365_0` (number, nullable): Adjusted occupancy (booked as a share of bookable nights, excluding blocked inventory) over the past 365 days.
- `nights_percent_open_365_0` (number, nullable): Share of nights open for booking over the past 365 days.
- `nights_percent_open_90_0` (number, nullable): Share of nights open for booking over the past 90 days.
- `nights_available_365_0` (integer, nullable): Number of unbooked, bookable nights over the past 365 days.
- `nights_blocked_365_0` (integer, nullable): Number of owner-blocked nights over the past 365 days.
- `nights_bookable_365_0` (integer, nullable): Available plus booked nights, excluding blocked nights, over the past 365 days.
- `nights_booked_365_0` (integer, nullable): Number of reserved nights over the past 365 days.
- `lead_time_365_0` (number, nullable): Average booking lead time in days over the past 365 days.
- `length_of_stay_365_0` (number, nullable): Average length of stay over the past 365 days.
- `revenue_365_0` (number, nullable): Rental revenue over the past 365 days.
- `revpar_365_0` (number, nullable): Revenue per available night over the past 365 days.
- `revpar_adjusted_365_0` (number, nullable): Revenue per bookable night, excluding blocked inventory, over the past 365 days.
- `distance_meters` (integer): Distance from the search origin, if applicable.
- `listing_created_at` (string (date-time), nullable): When the listing was first indexed by Wheelhouse (ISO-8601).
- `listing_last_updated` (string (date-time), nullable): When the listing data was last updated (ISO-8601).
- `updated_at` (string (date-time)): When this listing's metrics record was last updated (ISO-8601).

Example shape (generated from the schema; placeholder values, not a real response):

```json
[
  {
    "listing_id": 0,
    "title": "string",
    "source": "string",
    "url": "string",
    "thumb_url": "string",
    "owner_name": "string",
    "lat": 0,
    "long": 0,
    "market_id": 0,
    "currency": "string",
    "bedrooms": 0,
    "bathrooms": 0,
    "beds": 0,
    "sleeps": 0,
    "guests_included": 0,
    "room_type": "string",
    "property_type": "string",
    "amenities": [
      "string"
    ],
    "cleaning_fee": 0,
    "star_rating": 0,
    "review_count": 0,
    "adr_365_0": 0,
    "asking_rate_365_0": 0,
    "occupancy_365_0": 0,
    "occupancy_adjusted_365_0": 0,
    "nights_percent_open_365_0": 0,
    "nights_percent_open_90_0": 0,
    "nights_available_365_0": 0,
    "nights_blocked_365_0": 0,
    "nights_bookable_365_0": 0,
    "nights_booked_365_0": 0,
    "lead_time_365_0": 0,
    "length_of_stay_365_0": 0,
    "revenue_365_0": 0,
    "revpar_365_0": 0,
    "revpar_adjusted_365_0": 0,
    "distance_meters": 0,
    "listing_created_at": "2026-01-01T00:00:00Z",
    "listing_last_updated": "2026-01-01T00:00:00Z",
    "updated_at": "2026-01-01T00:00:00Z"
  }
]
```

### 400

Neither lat/long/radius nor market_ids were provided, or lat/long/radius were not sent together.

### 401

API key authorization failed.

### 429

Rate limit exceeded — the API key has sent too many requests. Wait before retrying. See the **Rate Limits** section in the overview for the recommended exponential backoff strategy.

Body (`application/json`): object

- `error` (string, example: `API token is at rate limit`)

Example shape (generated from the schema; placeholder values, not a real response):

```json
{
  "error": "API token is at rate limit"
}
```
