# Get yearly stats for a listing.

`GET /listings/{listing_id}/kpis/yearly`

> Wheelhouse Revenue Management API. Web version: https://docs.usewheelhouse.com/rm/reference/rm-get-listing-kpis-yearly · OpenAPI spec: https://docs.usewheelhouse.com/rm/openapi.yaml · Operation ID: `rmGetListingKpisYearly` · Tag: Listings

Returns per-year performance stats, ordered oldest-to-newest.

**Covers both past and future years** — from 5 calendar years ago through the year containing
the maximum calendar horizon (1.5 years from now), subject to the years Wheelhouse holds data
for. That last year includes only the nights up to the horizon, so its nights and revenue
cover part of the year. The current year and any that follow are forward-looking: they
reflect the bookings on the books so far plus asking rates for nights that are still open,
so they are not final and will change as bookings come in. Compare a year's `year` value
against today's date to tell which side of the line it falls on.

**Same time last year.** Pass `basis=stly` to get each year as it stood at the same time
last year. The row under a `year` holds the year before, as it stood 52 weeks ago, so a
year that was still ahead then counts only the bookings on the books at the time. Rows
sit under the current `year` they compare with, so the two bases can be joined on
`year`. `revenue_blocked` is `null`. Years with no stats for last year are absent.
`basis=stly` is in early access; accounts without early access get a 403.

All monetary values are in the listing's `currency`.

## Request

`GET https://api.usewheelhouse.com/ss_api/v1/listings/{listing_id}/kpis/yearly`

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). |
| `basis` | string | no | Return today's values (`current`) or the values as they stood at the same time last year (`stly`). See the description above for what `stly` returns. (one of: `current`, `stly`, default: `current`) |

### Example request

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

Yearly KPIs.

Body (`application/json`): object

- `currency` (string, example: `USD`): ISO-4217 currency code for all monetary values in this response.
- `data` (array of object `listing_stats_yearly_response`): Past and future years, ordered oldest-to-newest.
  - Each item: Performance stats for a single calendar year. The year may be in the past or in the future; future years are forward-looking (bookings on the books plus asking rates for open nights) rather than settled results.
  - `year` (string (date)): First day of the year these stats cover (ISO-8601 date). Compare against today's date to tell whether the year is complete, in progress, or still ahead.
  - `adr` (number, nullable): Average daily rate.
  - `adr_fees` (number, nullable): Average daily rate including fees.
  - `asking_rate` (number, nullable): Asking Rate (Booked + Available Nights): average nightly price across booked and available nights, excluding fees. A booked night counts at the rate it was booked for, an available night at its current price. Blocked nights are left out. `null` when no night qualifies. See `asking_rate_available` for available nights only.
  - `asking_rate_available` (number, nullable): Asking Rate (Available Nights): sum of nightly prices on available nights / number of available nights, excluding fees. Booked and blocked nights, and nights without a price, count in neither. `null`, not `0`, when no available night has a price.
  - `asking_rate_highest` (number, nullable): Asking Rate (Highest): highest nightly asking price on any night in the period, whether open, booked or blocked. `null` when no night has a price.
  - `asking_rate_lowest` (number, nullable): Asking Rate (Lowest): lowest nightly asking price on any night in the period, whether open, booked or blocked. `null` when no night has a price.
  - `bookings` (integer, nullable): Bookings: reservations with at least one night in the period. `null`, not `0`, when no reservation overlaps the period. Adds up the months in the period, so a stay that spans months counts once in each month it touches.
  - `lead_time` (number, nullable): Average days between booking and check-in.
  - `los` (number, nullable): Average length of stay in nights.
  - `nights_available` (number, nullable): Currently unbooked, bookable nights.
  - `nights_blocked` (number, nullable): Owner-blocked nights preventing bookings.
  - `nights_bookable` (number, nullable): Bookable nights (available plus booked, excluding blocked).
  - `nights_booked` (number, nullable): Currently reserved nights.
  - `nights_calendar` (number, nullable): Nights (Calendar): nights in the period, irrespective of listing status. For a listing with several units, counts the nights of each currently active unit.
  - `nights_percent_open` (number, nullable): Nights (Bookable %): bookable nights as a share of calendar nights.
  - `occupancy` (number, nullable): Occupancy rate (booked nights / calendar nights).
  - `occupancy_adjusted` (number, nullable): Open occupancy rate (booked nights / bookable nights).
  - `revenue` (number, nullable): Total revenue (rent only).
  - `revenue_available` (number, nullable): Potential earnings from currently available nights at current asking rates.
  - `revenue_blocked` (number, nullable): Unrealized revenue from blocked nights at current asking rates.
  - `revenue_fees` (number, nullable): Revenue including fees (rent plus fees) for booked nights.
  - `revenue_fees_taxes` (number, nullable): Revenue including fees and taxes for booked nights.
  - `revpar` (number, nullable): Revenue per available room night.
  - `revpar_fees` (number, nullable): RevPAR including fees.
  - `revpar_adjusted_occupancy_fees` (number, nullable): RevPAR including fees, excluding blocked nights.
  - `revpar_adjusted_occupancy` (number, nullable): RevPAR excluding blocked nights.

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

```json
{
  "currency": "USD",
  "data": [
    {
      "year": "2026-01-01",
      "adr": 0,
      "adr_fees": 0,
      "asking_rate": 0,
      "asking_rate_available": 0,
      "asking_rate_highest": 0,
      "asking_rate_lowest": 0,
      "bookings": 0,
      "lead_time": 0,
      "los": 0,
      "nights_available": 0,
      "nights_blocked": 0,
      "nights_bookable": 0,
      "nights_booked": 0,
      "nights_calendar": 0,
      "nights_percent_open": 0,
      "occupancy": 0,
      "occupancy_adjusted": 0,
      "revenue": 0,
      "revenue_available": 0,
      "revenue_blocked": 0,
      "revenue_fees": 0,
      "revenue_fees_taxes": 0,
      "revpar": 0,
      "revpar_fees": 0,
      "revpar_adjusted_occupancy_fees": 0,
      "revpar_adjusted_occupancy": 0
    }
  ]
}
```

### 401

API key authorization failed.

### 403

Listing authorization failed, or `basis=stly` was requested by an account without early access to it.

### 404

Listing not found.

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

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