Skip to content

Heatmaps API ​

All paths are relative to https://your-site.com/api/v1. Send Authorization: Bearer <token> and Accept: application/json; see authentication and errors.

MethodPathWhat it does
GET/sites/{site}/heatmapsPages with heatmap data (most viewed first, at most 200)
GET/sites/{site}/heatmaps/mapOne page's click, movement or scroll map for a segment

GET /sites/{site}/heatmaps ​

Pages with heatmap data (most viewed first, at most 200)

Pages are URLs without query string or hash; sites group further with the tracker's pageUrl command.

Parameters ​

NameInTypeRequiredDescription
sitepathintegeryes
devicequerystringOne of: desktop, mobile, tablet. Default "desktop".
qquerystringAddress or title contains (* stands for anything).

Responses ​

  • 200 — Pages.
  • 404 — Missing, or another account's.
Response fields
FieldTypeRequiredDescription
dataobject[]
data[].urlstring
data[].devicestring
data[].viewsinteger
data[].titlestring, nullableThe page title the tracker reported last.
data[].drawablebooleanA recording can draw this page (see the map's page.sample).
data[].sampleobject, nullableThe recording that draws the page (thumbnails): session id and the moment the page was opened.
data[].sample.sessionstring (uuid)
data[].sample.at_msinteger
data[].last_seen_atstring (date-time), nullable
bash
curl -X GET "https://your-site.com/api/v1/sites/{site}/heatmaps" \
  -H "Authorization: Bearer $REPLORA_TOKEN" \
  -H "Accept: application/json"

GET /sites/{site}/heatmaps/map ​

One page's click, movement or scroll map for a segment

kind=click: elements (top 200 by clicks: selector, label, clicks, rage, share %, spots = [rx, ry, n] inside the element, rounded to 5 %), points ([x as share of page width, y px, n] for clicks without an element), total, rage. kind=move: cells ([column 0–99 = % of page width, row of cell_height px, n]). kind=scroll: reach (share of views reaching each 5 % of the page), average, fold (% visible without scrolling). page.sample = {session, at_ms}: the recording and moment that draw the page (rebuild it with rrweb from GET /sites/{site}/sessions/{session}/events), or null.

Parameters ​

NameInTypeRequiredDescription
sitepathintegeryes
urlquerystringyes
kindquerystringOne of: click, move, scroll, attention. Default "click".
devicequerystringOne of: desktop, mobile, tablet. Default "desktop".
fromquerystring (date)
toquerystring (date)
sourcequerystringOne of: direct, search, social, email, paid, referral.
visitorquerystringOne of: new, returning.
referrerquerystringA referring domain (its subdomains count too; "www." is ignored). Click and scroll maps. At most 255 characters.
widthquerystringScreen width (click and scroll maps): xs under 768 px, sm 768–1023, md 1024–1439, lg 1440 and wider. One of: xs, sm, md, lg.

Responses ​

  • 200 — The map (see the description).
  • 404 — Missing, or another account's.
  • 422 — Validation failed.
bash
curl -X GET "https://your-site.com/api/v1/sites/{site}/heatmaps/map" \
  -H "Authorization: Bearer $REPLORA_TOKEN" \
  -H "Accept: application/json"

Replora: see what your visitors see.