---
title: "Get yield insights room and area occupancy"
method: GET
path: "/shop/yield-insights/room-occupancy"
tags: ["YieldInsights"]
---

# Get yield insights room and area occupancy

`GET /shop/yield-insights/room-occupancy`

Returns how full each of a site's bookable resources was by hour over a
recent reporting period, so an operator can see which rooms carry the demand
and which sit empty.

Each average is the share of that resource's bookable minutes which were
booked in that hour across the period, with time blocked out by staff
reducing capacity rather than counting as demand. An average is `null`
rather than `0` where nothing was bookable, so a closed hour reads
differently from an empty one.

Rows cover treatment rooms today; `kind` distinguishes them from bookable
areas, which are added as further rows once their capacity is measured.

`avgs` is empty until the underlying calculation has data to work from,
while the rows themselves are always returned, so a grid can render its
axes before any fill rate exists.

## Query parameters

- `site_id` string, uuid, required
- `period` 'last_30_days' | 'last_60_days' | 'last_90_days'

## Response `200`

The room and area occupancy grid was successfully retrieved.

- object
  - `data` YieldInsightsRoomOccupancy, required — How full each of a site's bookable resources was, by hour, over a reporting period. Separate from the [demand heatmap](/endpoints/YieldInsights#getYieldInsightsHeatmap) because a resource is measured individually rather than pooled into one weekday grid: an operator wants to know *which* room is quiet, not just when. The three threshold fields band those fill rates for display and are always present, whether or not there is any occupancy data. They are the same thresholds the demand heatmap returns, so the two grids colour identically.
    - `period` 'last_30_days' | 'last_60_days' | 'last_90_days', required — The reporting period the averages cover.
    - `window` YieldInsightsWindow, nullable, required — The concrete datetime window the requested `period` resolved to, or `null` when the site has no occupancy history at all to build a window from. When the site's data starts too recently to cover the whole requested period, `starts_at` reflects where the data actually begins rather than the full period.
      - `starts_at` string, date-time, required — When the reporting window starts.
      - `ends_at` string, date-time, required — When the reporting window ends.
    - `has_occupancy_data` boolean, required — Whether the site has any history to measure, and any resource to measure it against. False where either is missing, and the grid has nothing to render.
    - `heatmap` YieldInsightsRoomOccupancyRow[], required — One entry per bookable resource, in the order the site lists them.
      - `id` string, required — The room or bookable area this row measures.
      - `name` string, required
      - `kind` 'room' | 'bookable_area', required — Which kind of resource the row measures, so a grid can label or group rooms separately from bookable areas.
      - `avgs` object, required — Fill rate as a whole-number percentage, keyed by the hour's start in the site's local time (24-hour `HH:MM`). Only hours the resource was open appear. A value is `null` where nothing was bookable in that hour.
    - `quiet_threshold_percent` integer, required — The fill rate at or below which an hour counts as quiet.
    - `high_threshold_percent` integer, required — The fill rate at or above which an hour counts as high, up to `peak_threshold_percent`. Banding only; nothing is counted against it.
    - `peak_threshold_percent` integer, required — The fill rate at or above which an hour counts as a peak.

## Other responses

- `401` — The user is unauthenticated
- `403` — The authenticated user does not have permission.
- `422` — The request didn't pass validation

---

[API](https://skmtc.dev/try/apis/trybe-api.md) · [All operations](https://skmtc.dev/try/apis/trybe-api/llms.txt) · [OpenAPI document](https://skmtc-service-production.skmtc.workers.dev/v1/apis/try/trybe-api/revisions/f37f92702da5/schema)