# Get daily neighborhood occupancy and booking data for a listing.

`GET /listings/{listing_id}/neighborhood/occupancy`

> Wheelhouse Revenue Management API. Web version: https://docs.usewheelhouse.com/rm/reference/rm-get-neighborhood-occupancy · OpenAPI spec: https://docs.usewheelhouse.com/rm/openapi.yaml · Operation ID: `rmGetNeighborhoodOccupancy` · Tag: Neighborhood Data

Returns a daily time series of occupancy and booking model data for the listing's local
neighborhood cluster. This is the same data used to render the occupancy, expected
bookings, and observed bookings series in the Wheelhouse pricing chart.

- `occupancy` — raw occupancy rate (booked nights / calendar nights).
- `adjusted_occupancy` — occupancy computed against bookable (unblocked) nights only.
- `expected_bookings` — model-predicted booking count for the stay date.
- `expected_bookings_sd` — standard deviation of the expected bookings prediction.
- `observed_bookings` — actual booking count observed for the stay date.
- `calendar_nights` — total calendar nights in the cluster for the stay date.

Returns `404` if no neighborhood cluster is found for the listing's location, or if no
occupancy data has been generated for the cluster.

## Request

`GET https://api.usewheelhouse.com/ss_api/v1/listings/{listing_id}/neighborhood/occupancy`

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.

### Path parameters

| Name | Type | Required | Description |
| --- | --- | --- | --- |
| `listing_id` | string | yes | The channel's unique listing identifier, or the Wheelhouse listing ID when `channel` is `wheelhouse`. |

### Query parameters

| Name | Type | Required | Description |
| --- | --- | --- | --- |
| `channel` | string | yes | Channel name the listing is on (the `channel` field of the [/listings](https://docs.usewheelhouse.com/rm/reference/rm-get-listings.md) response), or the literal `wheelhouse` to read `listing_id` as a Wheelhouse listing ID instead. See [Identifying Listings](https://docs.usewheelhouse.com/rm/concepts/listings.md). |

### Example request

```bash
curl -X GET 'https://api.usewheelhouse.com/ss_api/v1/listings/{listing_id}/neighborhood/occupancy?channel=<channel>' \
  -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

Neighborhood occupancy and booking data.

Body (`application/json`): object `neighborhood_occupancy_response`

Daily neighborhood occupancy and bookings.

- `data` (array of object `neighborhood_occupancy_day`, required): Daily neighborhood occupancy entries ordered by stay date.
  - `stay_date` (string (date), required): The stay date (YYYY-MM-DD).
  - `occupancy` (number, nullable): Raw occupancy rate for the cluster on this date (booked nights / calendar nights).
  - `adjusted_occupancy` (number, nullable): Occupancy rate computed against bookable (unblocked) nights only.
  - `expected_bookings` (number, nullable): Model-predicted number of bookings for this stay date.
  - `expected_bookings_sd` (number, nullable): Standard deviation of the expected bookings prediction.
  - `observed_bookings` (number, nullable): Actual number of bookings observed for this stay date.
  - `calendar_nights` (integer, nullable): Total calendar nights in the neighborhood cluster for this stay date.

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

```json
{
  "data": [
    {
      "stay_date": "2026-01-01",
      "occupancy": 0,
      "adjusted_occupancy": 0,
      "expected_bookings": 0,
      "expected_bookings_sd": 0,
      "observed_bookings": 0,
      "calendar_nights": 0
    }
  ]
}
```

### 401

API key authorization failed.

### 403

Listing authorization failed.

### 404

Listing not found, or no neighborhood cluster or occupancy data found for this listing's location.

### 406

The listing is inactive. See the **Inactive Listings** section in the overview.

Body (`application/json`): object

- `error` (string, example: `Listing '12345' is inactive`)

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

```json
{
  "error": "Listing '12345' is inactive"
}
```

### 422

Listing is not covered by a Wheelhouse market, or has no location data.

### 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"
}
```
