---
title: "Get the yield insights demand heatmap"
method: GET
path: "/shop/yield-insights/heatmap"
tags: ["YieldInsights"]
---

# Get the yield insights demand heatmap

`GET /shop/yield-insights/heatmap`

Returns how full a site's bookable capacity was by weekday and hour over a
recent reporting period, so an operator can see when demand is heavy enough
to price against.

Each average is the share of bookable minutes that were booked in that
weekday and hour across the period — booked time over usable capacity, 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.

`type` selects which offerings the averages cover.

`has_occupancy_data` is always present, so a dashboard can decide whether to
render the grid before reading it. `heatmap` is empty until the underlying
calculation has data to work from.

Separate from the [yield insights summary](/endpoints/YieldInsights#getYieldInsights)
because `type` scopes only the grid: a dashboard switching between offering
types re-reads this without re-reading the summary.

## Query parameters

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

## Response `200`

The demand heatmap was successfully retrieved.

- object
  - `data` YieldInsightsHeatmap, required — How full a site's bookable capacity was by weekday and hour over a reporting period. The three threshold fields band those fill rates for display and are always present, whether or not there is any occupancy data. An hour is quiet at or below `quiet_threshold_percent`, peak at or above `peak_threshold_percent`, high from `high_threshold_percent` up to peak, and standard in between.
    - `period` 'last_30_days' | 'last_60_days' | 'last_90_days', required — The reporting period the averages cover.
    - `type` 'appointments' | 'sessions', required — Which offerings 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. False for a site with no completed days of trading, where `heatmap` is empty and the grid has nothing to render.
    - `heatmap` YieldInsightsHeatmapDay[], required — One entry per weekday the site is open. Empty until the underlying calculation has data to work from.
      - `day` 'mon' | 'tue' | 'wed' | 'thu' | 'fri' | 'sat' | 'sun', required
      - `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 site is 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. The same threshold the summary endpoint returns, so the grid and the opportunity counts band identically.
    - `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. The same threshold the summary endpoint returns.

## 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)