Developers
CountPort API
Read your sites, store PC health and visitor data from your own systems: BI, POS, signage or building management. A read-only REST API that answers in JSON, with the same figures as the dashboards and exports in CountPort Cloud.
- Base URL
- https://app.countport.com/api/v1
- Version
- 1.0.0
- Format
- JSON over HTTPS, read-only
- Limit
- 120 requests a minute per key
Getting started
- Create a key. In CountPort Cloud, an owner opens Settings › Integrations and selects Create key, then picks what the key may read, which sites and for how long. The key is shown once, so copy it then. The API is part of the Pro plan.
- Keep it on your server. Store the key in a secret store or an environment variable,
here
COUNTPORT_API_KEY. The API is for server-to-server use and sends no CORS headers, so call it from your backend, not from a web page. - Make the first request. List the sites the key may read:
curl "https://app.countport.com/api/v1/sites" \
-H "Authorization: Bearer $COUNTPORT_API_KEY"const res = await fetch("https://app.countport.com/api/v1/sites", {
headers: { Authorization: `Bearer ${process.env.COUNTPORT_API_KEY}` },
});
if (!res.ok) throw new Error(`${res.status}: ${(await res.json()).message}`);
const data = await res.json();import os
import requests
r = requests.get(
"https://app.countport.com/api/v1/sites",
headers={"Authorization": f"Bearer {os.environ['COUNTPORT_API_KEY']}"},
timeout=30,
)
r.raise_for_status()
data = r.json()
Then read data for one of them, here footfall per hour for one day. Use a site's id from the answer:
curl "https://app.countport.com/api/v1/sites/s_3f9c1a2b4d5e6f70/footfall?grain=hour&from=2026-10-22&to=2026-10-22" \
-H "Authorization: Bearer $COUNTPORT_API_KEY"const res = await fetch("https://app.countport.com/api/v1/sites/s_3f9c1a2b4d5e6f70/footfall?grain=hour&from=2026-10-22&to=2026-10-22", {
headers: { Authorization: `Bearer ${process.env.COUNTPORT_API_KEY}` },
});
if (!res.ok) throw new Error(`${res.status}: ${(await res.json()).message}`);
const data = await res.json();import os
import requests
r = requests.get(
"https://app.countport.com/api/v1/sites/s_3f9c1a2b4d5e6f70/footfall",
params={"grain": "hour", "from": "2026-10-22", "to": "2026-10-22"},
headers={"Authorization": f"Bearer {os.environ['COUNTPORT_API_KEY']}"},
timeout=30,
)
r.raise_for_status()
data = r.json()Authentication
Send the key in a header, in either form:
Authorization: Bearer cpk_…
X-API-Key: cpk_…- Never put a key in a URL. A request with a key in its address is refused with 400 before anything else. Revoke a key that was put in a URL.
- A key reads only its scopes, and only one site when it was created for one. Another scope answers 403; another site, or another organization's data, answers 404.
- Every key expires: you choose 30 days to 2 years when you create it. An owner can revoke a key at any time, and it stops working at once.
- A missing, expired or revoked key answers 401.
Scopes
| Scope | Named in CountPort Cloud | Endpoints |
|---|---|---|
| sites:read | Sites | List sites, Get a site |
| devices:read | Devices and camera health | List devices with health, Get a device with health |
| footfall:read | Footfall | Footfall |
| occupancy:read | Occupancy | Occupancy, People inside now |
| queue:read | Queue | Queue |
| heatmap:read | Heatmap and dwell | Dwell, Heatmap |
How the data works
Time buckets in site time
Every time series is a list of buckets of 15 minutes, an hour or a day (grain), in the site's own
time zone (site.timezone): the same buckets as the dashboards. Give from and
to as site-local dates (2026-10-22, both days included) or as RFC 3339
date-times (buckets that start from from up to, not including, to), both in the same form.
Each bucket has its start and end in UTC and its local date, start, end and UTC offset. On the days the clocks change, a
day has 23 or 25 hourly buckets; the repeated hour has fold: 1.
Coverage
Every bucket says how much of it was analysed. coverage is the share of the expected camera-seconds
that were analysed, and status is complete (90% or more),
partial or no_data.
Gaps are null, never 0
When nothing was analysed, every figure in the bucket is null and its status is
no_data. A counted zero is 0. Nothing is scaled up or filled in. To total
several buckets, add up analysedSeconds and expectedSeconds rather than
averaging coverage.
{
"start": "2026-10-22T09:00:00Z",
"end": "2026-10-22T10:00:00Z",
"local": "2026-10-22T10:00+01:00",
"localDate": "2026-10-22",
"localStart": "10:00",
"localEnd": "11:00",
"utcOffset": "+01:00",
"fold": 0,
"inProgress": false,
"value": 42,
"coverage": 1,
"status": "complete",
"analysedSeconds": 3600,
"expectedSeconds": 3600,
"lines": [
{
"lineId": "ln_4F7KQ2",
"deviceId": "dev_8a1e0c5b7d2f4936",
"cameraId": "cam_6TQ2M8",
"value": 42,
"coverage": 1,
"status": "complete",
"analysedSeconds": 3600,
"expectedSeconds": 3600
}
]
}The current bucket
Buckets that start after the time of the request are not listed. The bucket that contains it has
inProgress: true, and its figures are still growing.
How far one request reaches
- 15-minute buckets: up to 32 days. Hours: up to 93 days. Days: up to 732 days.
- Occupancy: 15 minutes or hours, up to 32 days. It restarts from 0 each day at the site's reset time.
- Heatmap: up to 31 days at any grain.
The API uses the same calculations as CountPort Cloud's dashboards, reports and exports, so the figures match to the last digit.
Paging
Time series come a page of buckets at a time: by default a day of 15-minute buckets (96), a week of hours (168) or a year of
days (366), and up to 1000 with limit. The heatmap sends 24 buckets a page, up to 48. Lists of sites
and devices come 100 at a time, up to 500.
When an answer has a nextCursor, send it back as cursor with the same other
parameters, until it is null. A cursor from another request answers 400.
import os
import requests
url = "https://app.countport.com/api/v1/sites/s_3f9c1a2b4d5e6f70/footfall"
params = {"grain": "15m", "from": "2026-10-01", "to": "2026-10-31"}
headers = {"Authorization": f"Bearer {os.environ['COUNTPORT_API_KEY']}"}
buckets = []
while True:
r = requests.get(url, params=params, headers=headers, timeout=30)
r.raise_for_status()
page = r.json()
buckets += page["buckets"]
if page["nextCursor"] is None:
break
params["cursor"] = page["nextCursor"]const url = new URL("https://app.countport.com/api/v1/sites/s_3f9c1a2b4d5e6f70/footfall");
url.search = new URLSearchParams({ grain: "15m", from: "2026-10-01", to: "2026-10-31" });
const buckets = [];
for (;;) {
const res = await fetch(url, { headers: { Authorization: `Bearer ${process.env.COUNTPORT_API_KEY}` } });
if (!res.ok) throw new Error(`${res.status}: ${(await res.json()).message}`);
const page = await res.json();
buckets.push(...page.buckets);
if (page.nextCursor === null) break;
url.searchParams.set("cursor", page.nextCursor);
}Errors and limits
An error answers with its HTTP status and a JSON body. The code is stable; the message is for people.
{
"code": "permission_denied",
"message": "This API key does not have the devices:read scope."
}| Status | Code | When |
|---|---|---|
| 400 | invalid_argument | Invalid parameters. |
| 401 | unauthenticated | No valid API key. |
| 403 | permission_denied | The key lacks the scope. |
| 404 | not_found | Not found, or outside the key's tenant or site. |
| 429 | rate_limited | Over the key's rate limit. |
| 500 | internal | Something failed on CountPort's side. Retry later. |
Rate limits
- Each key can make 120 requests a minute. Every answer carries
RateLimit-Limit. - Over the limit, the API answers 429 with
Retry-After: 60. Wait that many seconds, then retry. - After 20 requests with a wrong key in one minute from one address, that address gets 429 too.
- Answers are not cached (
Cache-Control: private, no-store).
Versioning
- Within v1, changes only add things: new endpoints, new optional parameters, new fields and new values. Ignore fields you do not know, and treat a value you do not know as "other".
- A change that would break a client goes to
/api/v2, which runs next to v1 for at least 12 months. Your IT contact hears about it first. - The OpenAPI document describes every endpoint and needs no key. Import it into Postman or Insomnia, or generate a client from it.
Sites
List sites
sites:readGET/api/v1/sites
The sites the key may read, ordered by id.
Parameters
| Name | In | Type | Description |
|---|---|---|---|
cursor | query | string | nextCursor of the previous page. |
limit | query | integer | Items per page (default 100). |
Request
curl "https://app.countport.com/api/v1/sites" \
-H "Authorization: Bearer $COUNTPORT_API_KEY"const res = await fetch("https://app.countport.com/api/v1/sites", {
headers: { Authorization: `Bearer ${process.env.COUNTPORT_API_KEY}` },
});
if (!res.ok) throw new Error(`${res.status}: ${(await res.json()).message}`);
const data = await res.json();import os
import requests
r = requests.get(
"https://app.countport.com/api/v1/sites",
headers={"Authorization": f"Bearer {os.environ['COUNTPORT_API_KEY']}"},
timeout=30,
)
r.raise_for_status()
data = r.json()Example answer
{
"sites": [
{
"id": "s_3f9c1a2b4d5e6f70",
"name": "Main Street",
"timezone": "Europe/London",
"groupId": null,
"status": "active",
"openingHours": {
"weekly": {
"mon": [
{
"open": "09:00",
"close": "20:00"
}
],
"tue": [
{
"open": "09:00",
"close": "20:00"
}
],
"wed": [
{
"open": "09:00",
"close": "20:00"
}
],
"thu": [
{
"open": "09:00",
"close": "20:00"
}
],
"fri": [
{
"open": "09:00",
"close": "21:00"
}
],
"sat": [
{
"open": "09:00",
"close": "21:00"
}
],
"sun": [
{
"open": "11:00",
"close": "17:00"
}
]
},
"exceptions": {
"2026-12-25": []
}
},
"occupancyResetTime": "04:00"
}
],
"nextCursor": null
}Answer fields (15)
| Field | Type | Description |
|---|---|---|
| sites | array of object | |
| sites[].id | string | |
| sites[].name | string | |
| sites[].timezone | string | |
| sites[].groupId | string or null | |
| sites[].status | one of: active, archived | |
| sites[].openingHours | object or null | Weekly site-local opening intervals and dated exceptions; null when not set, which CountPort Cloud treats as open 24 hours, 7 days (as a site whose every weekday is 00:00–24:00). |
| sites[].openingHours.weekly | map of array of object | |
| sites[].openingHours.weekly.<key>[].open | string | |
| sites[].openingHours.weekly.<key>[].close | string | |
| sites[].openingHours.exceptions | map of array of object | |
| sites[].openingHours.exceptions.<key>[].open | string | |
| sites[].openingHours.exceptions.<key>[].close | string | |
| sites[].occupancyResetTime | string | Site-local time occupancy restarts from 0 each day. |
| nextCursor | string or null | Pass as `cursor` to read the next page; null on the last page. |
Get a site
sites:readGET/api/v1/sites/{siteId}
One site with its time zone, opening hours and occupancy reset.
Parameters
| Name | In | Type | Description |
|---|---|---|---|
siteIdrequired | path | string | The site's id, from List sites. |
Request
curl "https://app.countport.com/api/v1/sites/s_3f9c1a2b4d5e6f70" \
-H "Authorization: Bearer $COUNTPORT_API_KEY"const res = await fetch("https://app.countport.com/api/v1/sites/s_3f9c1a2b4d5e6f70", {
headers: { Authorization: `Bearer ${process.env.COUNTPORT_API_KEY}` },
});
if (!res.ok) throw new Error(`${res.status}: ${(await res.json()).message}`);
const data = await res.json();import os
import requests
r = requests.get(
"https://app.countport.com/api/v1/sites/s_3f9c1a2b4d5e6f70",
headers={"Authorization": f"Bearer {os.environ['COUNTPORT_API_KEY']}"},
timeout=30,
)
r.raise_for_status()
data = r.json()Example answer
{
"id": "s_3f9c1a2b4d5e6f70",
"name": "Main Street",
"timezone": "Europe/London",
"groupId": null,
"status": "active",
"openingHours": {
"weekly": {
"mon": [
{
"open": "09:00",
"close": "20:00"
}
],
"tue": [
{
"open": "09:00",
"close": "20:00"
}
],
"wed": [
{
"open": "09:00",
"close": "20:00"
}
],
"thu": [
{
"open": "09:00",
"close": "20:00"
}
],
"fri": [
{
"open": "09:00",
"close": "21:00"
}
],
"sat": [
{
"open": "09:00",
"close": "21:00"
}
],
"sun": [
{
"open": "11:00",
"close": "17:00"
}
]
},
"exceptions": {
"2026-12-25": []
}
},
"occupancyResetTime": "04:00"
}Answer fields (13)
| Field | Type | Description |
|---|---|---|
| id | string | |
| name | string | |
| timezone | string | |
| groupId | string or null | |
| status | one of: active, archived | |
| openingHours | object or null | Weekly site-local opening intervals and dated exceptions; null when not set, which CountPort Cloud treats as open 24 hours, 7 days (as a site whose every weekday is 00:00–24:00). |
| openingHours.weekly | map of array of object | |
| openingHours.weekly.<key>[].open | string | |
| openingHours.weekly.<key>[].close | string | |
| openingHours.exceptions | map of array of object | |
| openingHours.exceptions.<key>[].open | string | |
| openingHours.exceptions.<key>[].close | string | |
| occupancyResetTime | string | Site-local time occupancy restarts from 0 each day. |
Devices
List devices with health
devices:readGET/api/v1/devices
Devices (store PCs) the key may read, ordered by id, with their health and their cameras' health.
Parameters
| Name | In | Type | Description |
|---|---|---|---|
cursor | query | string | nextCursor of the previous page. |
limit | query | integer | Items per page (default 100). |
site | query | string | Only the devices of this site. |
Request
curl "https://app.countport.com/api/v1/devices" \
-H "Authorization: Bearer $COUNTPORT_API_KEY"const res = await fetch("https://app.countport.com/api/v1/devices", {
headers: { Authorization: `Bearer ${process.env.COUNTPORT_API_KEY}` },
});
if (!res.ok) throw new Error(`${res.status}: ${(await res.json()).message}`);
const data = await res.json();import os
import requests
r = requests.get(
"https://app.countport.com/api/v1/devices",
headers={"Authorization": f"Bearer {os.environ['COUNTPORT_API_KEY']}"},
timeout=30,
)
r.raise_for_status()
data = r.json()Example answer
{
"devices": [
{
"id": "dev_8a1e0c5b7d2f4936",
"name": "Main Street PC",
"siteId": "s_3f9c1a2b4d5e6f70",
"state": "commissioned",
"deviceClass": "store_pc",
"packageVersion": "1.0.1",
"os": "ubuntu",
"arch": "x86_64",
"health": {
"status": "online",
"lastSeenAt": "2026-10-22T13:41:50Z",
"connected": true,
"issues": [],
"unsentMinutes": 0,
"clockOffsetMs": 3
},
"cameras": [
{
"id": "cam_6TQ2M8",
"name": "Entrance",
"enabled": true,
"state": "online",
"streamState": "streaming",
"decodeFps": 15,
"analysedFps": 10,
"lastMinuteCoverageSeconds": 60,
"lastFrameAt": "2026-10-22T13:42:04Z",
"reconnects": 0
},
{
"id": "cam_9XK4P1",
"name": "Checkout",
"enabled": true,
"state": "online",
"streamState": "streaming",
"decodeFps": 15,
"analysedFps": 10,
"lastMinuteCoverageSeconds": 60,
"lastFrameAt": "2026-10-22T13:42:04Z",
"reconnects": 1
}
]
}
],
"nextCursor": null
}Answer fields (28)
| Field | Type | Description |
|---|---|---|
| devices | array of object | |
| devices[].id | string | |
| devices[].name | string | |
| devices[].siteId | string or null | |
| devices[].state | one of: awaiting_install, commissioned, retired, decommissioned | |
| devices[].deviceClass | one of: store_pc, camera | |
| devices[].packageVersion | string or null | |
| devices[].os | string or null | |
| devices[].arch | string or null | |
| devices[].health | object | |
| devices[].health.status | one of: never_seen, online, degraded, offline, unpaired | unpaired: the PC was unpaired on site and reports nothing until it is paired again. |
| devices[].health.lastSeenAt | string (date-time) or null | Last heartbeat or control-plane traffic (cloud clock). |
| devices[].health.connected | boolean | A control-plane connection is open now. |
| devices[].health.issues | array of one of: engine_not_running, camera_not_streaming, backlog, rows_dropped, clock_offset, cpu_high, config_rejected | |
| devices[].health.unsentMinutes | integer or null | Minutes of counts still in the device's outbox (last heartbeat). |
| devices[].health.clockOffsetMs | integer or null | |
| devices[].cameras | array of object | |
| devices[].cameras[].id | string | The device's own camera id (the cameraId in analytics). |
| devices[].cameras[].name | string | |
| devices[].cameras[].enabled | boolean | |
| devices[].cameras[].state | one of: unknown, online, offline, error | |
| devices[].cameras[].streamState | one of: connecting, streaming, backoff, disabled, error, or null | |
| devices[].cameras[].decodeFps | number or null | |
| devices[].cameras[].analysedFps | number or null | |
| devices[].cameras[].lastMinuteCoverageSeconds | integer or null | |
| devices[].cameras[].lastFrameAt | string (date-time) or null | Last decoded frame (device clock). |
| devices[].cameras[].reconnects | integer or null | |
| nextCursor | string or null | Pass as `cursor` to read the next page; null on the last page. |
Get a device with health
devices:readGET/api/v1/devices/{deviceId}
One device with its health and its cameras' health.
Parameters
| Name | In | Type | Description |
|---|---|---|---|
deviceIdrequired | path | string | The device's id, from List devices. |
Request
curl "https://app.countport.com/api/v1/devices/dev_8a1e0c5b7d2f4936" \
-H "Authorization: Bearer $COUNTPORT_API_KEY"const res = await fetch("https://app.countport.com/api/v1/devices/dev_8a1e0c5b7d2f4936", {
headers: { Authorization: `Bearer ${process.env.COUNTPORT_API_KEY}` },
});
if (!res.ok) throw new Error(`${res.status}: ${(await res.json()).message}`);
const data = await res.json();import os
import requests
r = requests.get(
"https://app.countport.com/api/v1/devices/dev_8a1e0c5b7d2f4936",
headers={"Authorization": f"Bearer {os.environ['COUNTPORT_API_KEY']}"},
timeout=30,
)
r.raise_for_status()
data = r.json()Example answer
{
"id": "dev_8a1e0c5b7d2f4936",
"name": "Main Street PC",
"siteId": "s_3f9c1a2b4d5e6f70",
"state": "commissioned",
"deviceClass": "store_pc",
"packageVersion": "1.0.1",
"os": "ubuntu",
"arch": "x86_64",
"health": {
"status": "online",
"lastSeenAt": "2026-10-22T13:41:50Z",
"connected": true,
"issues": [],
"unsentMinutes": 0,
"clockOffsetMs": 3
},
"cameras": [
{
"id": "cam_6TQ2M8",
"name": "Entrance",
"enabled": true,
"state": "online",
"streamState": "streaming",
"decodeFps": 15,
"analysedFps": 10,
"lastMinuteCoverageSeconds": 60,
"lastFrameAt": "2026-10-22T13:42:04Z",
"reconnects": 0
},
{
"id": "cam_9XK4P1",
"name": "Checkout",
"enabled": true,
"state": "online",
"streamState": "streaming",
"decodeFps": 15,
"analysedFps": 10,
"lastMinuteCoverageSeconds": 60,
"lastFrameAt": "2026-10-22T13:42:04Z",
"reconnects": 1
}
]
}Answer fields (26)
| Field | Type | Description |
|---|---|---|
| id | string | |
| name | string | |
| siteId | string or null | |
| state | one of: awaiting_install, commissioned, retired, decommissioned | |
| deviceClass | one of: store_pc, camera | |
| packageVersion | string or null | |
| os | string or null | |
| arch | string or null | |
| health | object | |
| health.status | one of: never_seen, online, degraded, offline, unpaired | unpaired: the PC was unpaired on site and reports nothing until it is paired again. |
| health.lastSeenAt | string (date-time) or null | Last heartbeat or control-plane traffic (cloud clock). |
| health.connected | boolean | A control-plane connection is open now. |
| health.issues | array of one of: engine_not_running, camera_not_streaming, backlog, rows_dropped, clock_offset, cpu_high, config_rejected | |
| health.unsentMinutes | integer or null | Minutes of counts still in the device's outbox (last heartbeat). |
| health.clockOffsetMs | integer or null | |
| cameras | array of object | |
| cameras[].id | string | The device's own camera id (the cameraId in analytics). |
| cameras[].name | string | |
| cameras[].enabled | boolean | |
| cameras[].state | one of: unknown, online, offline, error | |
| cameras[].streamState | one of: connecting, streaming, backoff, disabled, error, or null | |
| cameras[].decodeFps | number or null | |
| cameras[].analysedFps | number or null | |
| cameras[].lastMinuteCoverageSeconds | integer or null | |
| cameras[].lastFrameAt | string (date-time) or null | Last decoded frame (device clock). |
| cameras[].reconnects | integer or null |
Analytics
Footfall
footfall:readGET/api/v1/sites/{siteId}/footfall
Footfall — the IN count of entrance-role lines only — for the site and for each entrance line, per bucket of site time (15 minutes, hour or day), each bucket with its coverage; a bucket with nothing analysed has null figures and status no_data — a gap, never 0. Buckets that start after the time of the read are not listed; the one containing it is inProgress. Paged by bucket: pass nextCursor as cursor with the same grain, from and to.
Parameters
| Name | In | Type | Description |
|---|---|---|---|
siteIdrequired | path | string | The site's id, from List sites. |
grainrequired | query | one of: 15m, hour, day | Bucket size in site time. |
fromrequired | query | string | Site-local date (inclusive) or RFC 3339 instant (buckets starting at or after it). |
torequired | query | string | Site-local date (inclusive) or RFC 3339 instant (buckets starting before it). Use the same form as from. |
cursor | query | string | nextCursor of the previous page. |
limit | query | integer | Buckets per page (default: a day of 15-minute buckets, a week of hours, a year of days; heatmap 24, at most 48). |
Request
curl "https://app.countport.com/api/v1/sites/s_3f9c1a2b4d5e6f70/footfall?grain=hour&from=2026-10-22&to=2026-10-22" \
-H "Authorization: Bearer $COUNTPORT_API_KEY"const res = await fetch("https://app.countport.com/api/v1/sites/s_3f9c1a2b4d5e6f70/footfall?grain=hour&from=2026-10-22&to=2026-10-22", {
headers: { Authorization: `Bearer ${process.env.COUNTPORT_API_KEY}` },
});
if (!res.ok) throw new Error(`${res.status}: ${(await res.json()).message}`);
const data = await res.json();import os
import requests
r = requests.get(
"https://app.countport.com/api/v1/sites/s_3f9c1a2b4d5e6f70/footfall",
params={"grain": "hour", "from": "2026-10-22", "to": "2026-10-22"},
headers={"Authorization": f"Bearer {os.environ['COUNTPORT_API_KEY']}"},
timeout=30,
)
r.raise_for_status()
data = r.json()Example answer
{
"site": {
"id": "s_3f9c1a2b4d5e6f70",
"name": "Main Street",
"timezone": "Europe/London"
},
"grain": "hour",
"lines": [
{
"lineId": "ln_4F7KQ2",
"deviceId": "dev_8a1e0c5b7d2f4936",
"cameraId": "cam_6TQ2M8",
"name": "Front door",
"cameraName": "Entrance"
}
],
"buckets": [
{
"start": "2026-10-22T09:00:00Z",
"end": "2026-10-22T10:00:00Z",
"local": "2026-10-22T10:00+01:00",
"localDate": "2026-10-22",
"localStart": "10:00",
"localEnd": "11:00",
"utcOffset": "+01:00",
"fold": 0,
"inProgress": false,
"value": 42,
"coverage": 1,
"status": "complete",
"analysedSeconds": 3600,
"expectedSeconds": 3600,
"lines": [
{
"lineId": "ln_4F7KQ2",
"deviceId": "dev_8a1e0c5b7d2f4936",
"cameraId": "cam_6TQ2M8",
"value": 42,
"coverage": 1,
"status": "complete",
"analysedSeconds": 3600,
"expectedSeconds": 3600
}
]
},
{
"start": "2026-10-22T10:00:00Z",
"end": "2026-10-22T11:00:00Z",
"local": "2026-10-22T11:00+01:00",
"localDate": "2026-10-22",
"localStart": "11:00",
"localEnd": "12:00",
"utcOffset": "+01:00",
"fold": 0,
"inProgress": false,
"value": 57,
"coverage": 0.8333,
"status": "partial",
"analysedSeconds": 3000,
"expectedSeconds": 3600,
"lines": [
{
"lineId": "ln_4F7KQ2",
"deviceId": "dev_8a1e0c5b7d2f4936",
"cameraId": "cam_6TQ2M8",
"value": 57,
"coverage": 0.8333,
"status": "partial",
"analysedSeconds": 3000,
"expectedSeconds": 3600
}
]
},
{
"start": "2026-10-22T11:00:00Z",
"end": "2026-10-22T12:00:00Z",
"local": "2026-10-22T12:00+01:00",
"localDate": "2026-10-22",
"localStart": "12:00",
"localEnd": "13:00",
"utcOffset": "+01:00",
"fold": 0,
"inProgress": false,
"value": null,
"coverage": 0,
"status": "no_data",
"analysedSeconds": 0,
"expectedSeconds": 3600,
"lines": [
{
"lineId": "ln_4F7KQ2",
"deviceId": "dev_8a1e0c5b7d2f4936",
"cameraId": "cam_6TQ2M8",
"value": null,
"coverage": 0,
"status": "no_data",
"analysedSeconds": 0,
"expectedSeconds": 3600
}
]
}
],
"nextCursor": null
}Answer fields (36)
| Field | Type | Description |
|---|---|---|
| site | object | |
| site.id | string | |
| site.name | string | |
| site.timezone | string | IANA time zone every bucket is in. |
| grain | one of: 15m, hour, day | Bucket size in site time. |
| lines | array of object | Entrance-role lines expected or reporting in the page. |
| lines[].lineId | string | |
| lines[].name | string | |
| lines[].deviceId | string | |
| lines[].cameraId | string | The device's own camera id. |
| lines[].cameraName | string | |
| buckets | array of object | |
| buckets[].start | string (date-time) | Bucket start (UTC), inclusive. |
| buckets[].end | string (date-time) | Bucket end (UTC), exclusive. |
| buckets[].local | string | Site-local start with its UTC offset. |
| buckets[].localDate | string | Site-local date of the start. |
| buckets[].localStart | string | Site-local wall-clock start. |
| buckets[].localEnd | string | Site-local wall-clock end ("24:00" at midnight). |
| buckets[].utcOffset | string | |
| buckets[].fold | one of: 0, 1 | 1 for the repeated wall-clock hour on the night the clocks go back. |
| buckets[].inProgress | boolean | The bucket contains the time of the read; its figures are still growing. |
| buckets[].value | integer or null | IN count of every entrance line together; null = not analysed. |
| buckets[].coverage | number or null | Share of the camera-seconds the bucket's lines or zones were expected to analyse that they did analyse (floored to 4 decimals); null when nothing was expected. |
| buckets[].status | one of: complete, partial, no_data | complete: coverage ≥ 0.9; partial: some but less; no_data: nothing analysed (every figure is null — a gap, never 0). |
| buckets[].analysedSeconds | integer | Camera-seconds analysed. |
| buckets[].expectedSeconds | integer | Camera-seconds expected (installed, signed off, line or zone drawn). |
| buckets[].lines | array of object | |
| buckets[].lines[].lineId | string | |
| buckets[].lines[].deviceId | string | |
| buckets[].lines[].cameraId | string | The device's own camera id. |
| buckets[].lines[].value | integer or null | |
| buckets[].lines[].coverage | number or null | Share of the camera-seconds the bucket's lines or zones were expected to analyse that they did analyse (floored to 4 decimals); null when nothing was expected. |
| buckets[].lines[].status | one of: complete, partial, no_data | complete: coverage ≥ 0.9; partial: some but less; no_data: nothing analysed (every figure is null — a gap, never 0). |
| buckets[].lines[].analysedSeconds | integer | Camera-seconds analysed. |
| buckets[].lines[].expectedSeconds | integer | Camera-seconds expected (installed, signed off, line or zone drawn). |
| nextCursor | string or null | Pass as `cursor` to read the next page; null on the last page. |
Occupancy
occupancy:readGET/api/v1/sites/{siteId}/occupancy
People inside (entrance IN − OUT since the daily reset, never below 0, with manual corrections) per bucket of site time (15 minutes, hour or day), each bucket with its coverage; a bucket with nothing analysed has null figures and status no_data — a gap, never 0. Buckets that start after the time of the read are not listed; the one containing it is inProgress. Paged by bucket: pass nextCursor as cursor with the same grain, from and to.
Parameters
| Name | In | Type | Description |
|---|---|---|---|
siteIdrequired | path | string | The site's id, from List sites. |
grainrequired | query | one of: 15m, hour | Occupancy is computed from quarter hours: 15m or hour. |
fromrequired | query | string | Site-local date (inclusive) or RFC 3339 instant (buckets starting at or after it). |
torequired | query | string | Site-local date (inclusive) or RFC 3339 instant (buckets starting before it). Use the same form as from. |
cursor | query | string | nextCursor of the previous page. |
limit | query | integer | Buckets per page (default: a day of 15-minute buckets, a week of hours, a year of days; heatmap 24, at most 48). |
Request
curl "https://app.countport.com/api/v1/sites/s_3f9c1a2b4d5e6f70/occupancy?grain=hour&from=2026-10-22&to=2026-10-22" \
-H "Authorization: Bearer $COUNTPORT_API_KEY"const res = await fetch("https://app.countport.com/api/v1/sites/s_3f9c1a2b4d5e6f70/occupancy?grain=hour&from=2026-10-22&to=2026-10-22", {
headers: { Authorization: `Bearer ${process.env.COUNTPORT_API_KEY}` },
});
if (!res.ok) throw new Error(`${res.status}: ${(await res.json()).message}`);
const data = await res.json();import os
import requests
r = requests.get(
"https://app.countport.com/api/v1/sites/s_3f9c1a2b4d5e6f70/occupancy",
params={"grain": "hour", "from": "2026-10-22", "to": "2026-10-22"},
headers={"Authorization": f"Bearer {os.environ['COUNTPORT_API_KEY']}"},
timeout=30,
)
r.raise_for_status()
data = r.json()Example answer
{
"site": {
"id": "s_3f9c1a2b4d5e6f70",
"name": "Main Street",
"timezone": "Europe/London"
},
"grain": "hour",
"resetTime": "04:00",
"buckets": [
{
"start": "2026-10-22T09:00:00Z",
"end": "2026-10-22T10:00:00Z",
"local": "2026-10-22T10:00+01:00",
"localDate": "2026-10-22",
"localStart": "10:00",
"localEnd": "11:00",
"utcOffset": "+01:00",
"fold": 0,
"inProgress": false,
"value": 18,
"peak": 23,
"in": 64,
"out": 46,
"clamped": 0,
"corrections": 0,
"uncertain": false,
"businessDate": "2026-10-22",
"coverage": 1,
"status": "complete",
"analysedSeconds": 3600,
"expectedSeconds": 3600
},
{
"start": "2026-10-22T10:00:00Z",
"end": "2026-10-22T11:00:00Z",
"local": "2026-10-22T11:00+01:00",
"localDate": "2026-10-22",
"localStart": "11:00",
"localEnd": "12:00",
"utcOffset": "+01:00",
"fold": 0,
"inProgress": false,
"value": 25,
"peak": 31,
"in": 57,
"out": 50,
"clamped": 0,
"corrections": 0,
"uncertain": true,
"businessDate": "2026-10-22",
"coverage": 0.8333,
"status": "partial",
"analysedSeconds": 3000,
"expectedSeconds": 3600
}
],
"nextCursor": null
}Answer fields (29)
| Field | Type | Description |
|---|---|---|
| site | object | |
| site.id | string | |
| site.name | string | |
| site.timezone | string | IANA time zone every bucket is in. |
| grain | one of: 15m, hour, day | Bucket size in site time. |
| resetTime | string | |
| buckets | array of object | |
| buckets[].start | string (date-time) | Bucket start (UTC), inclusive. |
| buckets[].end | string (date-time) | Bucket end (UTC), exclusive. |
| buckets[].local | string | Site-local start with its UTC offset. |
| buckets[].localDate | string | Site-local date of the start. |
| buckets[].localStart | string | Site-local wall-clock start. |
| buckets[].localEnd | string | Site-local wall-clock end ("24:00" at midnight). |
| buckets[].utcOffset | string | |
| buckets[].fold | one of: 0, 1 | 1 for the repeated wall-clock hour on the night the clocks go back. |
| buckets[].inProgress | boolean | The bucket contains the time of the read; its figures are still growing. |
| buckets[].value | integer or null | People inside at the bucket's end; null when not analysed. |
| buckets[].peak | integer or null | |
| buckets[].in | integer or null | |
| buckets[].out | integer or null | |
| buckets[].clamped | integer | People dropped by the never-below-zero rule in the bucket. |
| buckets[].corrections | integer | Manual corrections applied in the bucket. |
| buckets[].uncertain | boolean | A quarter hour since the last reset was partial or not analysed. |
| buckets[].businessDate | string | |
| buckets[].coverage | number or null | Share of the camera-seconds the bucket's lines or zones were expected to analyse that they did analyse (floored to 4 decimals); null when nothing was expected. |
| buckets[].status | one of: complete, partial, no_data | complete: coverage ≥ 0.9; partial: some but less; no_data: nothing analysed (every figure is null — a gap, never 0). |
| buckets[].analysedSeconds | integer | Camera-seconds analysed. |
| buckets[].expectedSeconds | integer | Camera-seconds expected (installed, signed off, line or zone drawn). |
| nextCursor | string or null | Pass as `cursor` to read the next page; null on the last page. |
People inside now
occupancy:readGET/api/v1/sites/{siteId}/occupancy/live
People inside now, from the minutes committed so far, with their freshness (stale after 6 minutes).
Parameters
| Name | In | Type | Description |
|---|---|---|---|
siteIdrequired | path | string | The site's id, from List sites. |
Request
curl "https://app.countport.com/api/v1/sites/s_3f9c1a2b4d5e6f70/occupancy/live" \
-H "Authorization: Bearer $COUNTPORT_API_KEY"const res = await fetch("https://app.countport.com/api/v1/sites/s_3f9c1a2b4d5e6f70/occupancy/live", {
headers: { Authorization: `Bearer ${process.env.COUNTPORT_API_KEY}` },
});
if (!res.ok) throw new Error(`${res.status}: ${(await res.json()).message}`);
const data = await res.json();import os
import requests
r = requests.get(
"https://app.countport.com/api/v1/sites/s_3f9c1a2b4d5e6f70/occupancy/live",
headers={"Authorization": f"Bearer {os.environ['COUNTPORT_API_KEY']}"},
timeout=30,
)
r.raise_for_status()
data = r.json()Example answer
{
"site": {
"id": "s_3f9c1a2b4d5e6f70",
"name": "Main Street",
"timezone": "Europe/London"
},
"at": "2026-10-22T13:42:05Z",
"value": 27,
"status": "live",
"businessDate": "2026-10-22",
"resetTime": "04:00",
"resetAt": "2026-10-22T03:00:00Z",
"nextResetAt": "2026-10-23T03:00:00Z",
"asOf": "2026-10-22T13:41:00Z",
"freshnessSeconds": 65,
"in": 412,
"out": 385,
"clampedPeople": 0,
"corrections": 0,
"uncertain": false,
"uncertainSince": null,
"coverage": 1,
"entranceLines": 1,
"linesReporting": 1
}Answer fields (22)
| Field | Type | Description |
|---|---|---|
| site | object | |
| site.id | string | |
| site.name | string | |
| site.timezone | string | IANA time zone every bucket is in. |
| at | string (date-time) | Time of the read. |
| value | integer or null | |
| status | one of: live, stale, no_data, no_entrances | |
| businessDate | string | |
| resetTime | string | |
| resetAt | string (date-time) | The last daily reset. |
| nextResetAt | string (date-time) | The next daily reset. |
| asOf | string (date-time) or null | End of the newest minute every reporting entrance line delivered. |
| freshnessSeconds | integer or null | |
| in | integer or null | |
| out | integer or null | |
| clampedPeople | integer | |
| corrections | integer | |
| uncertain | boolean | |
| uncertainSince | string (date-time) or null | First quarter hour since the reset that was partial or not analysed. |
| coverage | number or null | |
| entranceLines | integer | |
| linesReporting | integer |
Queue
queue:readGET/api/v1/sites/{siteId}/queue
Queue length, waiting and service time per queue zone per bucket of site time (15 minutes, hour or day), each bucket with its coverage; a bucket with nothing analysed has null figures and status no_data — a gap, never 0. Buckets that start after the time of the read are not listed; the one containing it is inProgress. Paged by bucket: pass nextCursor as cursor with the same grain, from and to.
Parameters
| Name | In | Type | Description |
|---|---|---|---|
siteIdrequired | path | string | The site's id, from List sites. |
grainrequired | query | one of: 15m, hour, day | Bucket size in site time. |
fromrequired | query | string | Site-local date (inclusive) or RFC 3339 instant (buckets starting at or after it). |
torequired | query | string | Site-local date (inclusive) or RFC 3339 instant (buckets starting before it). Use the same form as from. |
cursor | query | string | nextCursor of the previous page. |
limit | query | integer | Buckets per page (default: a day of 15-minute buckets, a week of hours, a year of days; heatmap 24, at most 48). |
Request
curl "https://app.countport.com/api/v1/sites/s_3f9c1a2b4d5e6f70/queue?grain=hour&from=2026-10-22&to=2026-10-22" \
-H "Authorization: Bearer $COUNTPORT_API_KEY"const res = await fetch("https://app.countport.com/api/v1/sites/s_3f9c1a2b4d5e6f70/queue?grain=hour&from=2026-10-22&to=2026-10-22", {
headers: { Authorization: `Bearer ${process.env.COUNTPORT_API_KEY}` },
});
if (!res.ok) throw new Error(`${res.status}: ${(await res.json()).message}`);
const data = await res.json();import os
import requests
r = requests.get(
"https://app.countport.com/api/v1/sites/s_3f9c1a2b4d5e6f70/queue",
params={"grain": "hour", "from": "2026-10-22", "to": "2026-10-22"},
headers={"Authorization": f"Bearer {os.environ['COUNTPORT_API_KEY']}"},
timeout=30,
)
r.raise_for_status()
data = r.json()Example answer
{
"site": {
"id": "s_3f9c1a2b4d5e6f70",
"name": "Main Street",
"timezone": "Europe/London"
},
"grain": "hour",
"zones": [
{
"zoneId": "zn_2B8V5Q",
"deviceId": "dev_8a1e0c5b7d2f4936",
"cameraId": "cam_9XK4P1",
"name": "Tills",
"cameraName": "Checkout",
"capacity": 8,
"totalCashiers": 3
}
],
"buckets": [
{
"start": "2026-10-22T09:00:00Z",
"end": "2026-10-22T10:00:00Z",
"local": "2026-10-22T10:00+01:00",
"localDate": "2026-10-22",
"localStart": "10:00",
"localEnd": "11:00",
"utcOffset": "+01:00",
"fold": 0,
"inProgress": false,
"zones": [
{
"zoneId": "zn_2B8V5Q",
"deviceId": "dev_8a1e0c5b7d2f4936",
"cameraId": "cam_9XK4P1",
"avgLength": 2.4,
"maxLength": 6,
"minLength": 0,
"avgWaitSeconds": 95.5,
"avgServiceSeconds": 70.2,
"entries": 48,
"leadEntries": 45,
"labelMinutes": {
"empty": 12,
"low": 30,
"moderate": 15,
"high": 3
},
"coverage": 1,
"status": "complete",
"analysedSeconds": 3600,
"expectedSeconds": 3600
}
]
},
{
"start": "2026-10-22T10:00:00Z",
"end": "2026-10-22T11:00:00Z",
"local": "2026-10-22T11:00+01:00",
"localDate": "2026-10-22",
"localStart": "11:00",
"localEnd": "12:00",
"utcOffset": "+01:00",
"fold": 0,
"inProgress": false,
"zones": [
{
"zoneId": "zn_2B8V5Q",
"deviceId": "dev_8a1e0c5b7d2f4936",
"cameraId": "cam_9XK4P1",
"avgLength": 3.1,
"maxLength": 8,
"minLength": 1,
"avgWaitSeconds": 121,
"avgServiceSeconds": 68.4,
"entries": 61,
"leadEntries": 58,
"labelMinutes": {
"empty": 4,
"low": 27,
"moderate": 21,
"high": 8
},
"coverage": 1,
"status": "complete",
"analysedSeconds": 3600,
"expectedSeconds": 3600
}
]
}
],
"nextCursor": null
}Answer fields (44)
| Field | Type | Description |
|---|---|---|
| site | object | |
| site.id | string | |
| site.name | string | |
| site.timezone | string | IANA time zone every bucket is in. |
| grain | one of: 15m, hour, day | Bucket size in site time. |
| zones | array of object | |
| zones[].zoneId | string | |
| zones[].name | string | |
| zones[].deviceId | string | |
| zones[].cameraId | string | The device's own camera id. |
| zones[].cameraName | string | |
| zones[].capacity | number or null | |
| zones[].totalCashiers | integer or null | |
| buckets | array of object | |
| buckets[].start | string (date-time) | Bucket start (UTC), inclusive. |
| buckets[].end | string (date-time) | Bucket end (UTC), exclusive. |
| buckets[].local | string | Site-local start with its UTC offset. |
| buckets[].localDate | string | Site-local date of the start. |
| buckets[].localStart | string | Site-local wall-clock start. |
| buckets[].localEnd | string | Site-local wall-clock end ("24:00" at midnight). |
| buckets[].utcOffset | string | |
| buckets[].fold | one of: 0, 1 | 1 for the repeated wall-clock hour on the night the clocks go back. |
| buckets[].inProgress | boolean | The bucket contains the time of the read; its figures are still growing. |
| buckets[].zones | array of object | |
| buckets[].zones[].zoneId | string | |
| buckets[].zones[].deviceId | string | |
| buckets[].zones[].cameraId | string | The device's own camera id. |
| buckets[].zones[].avgLength | number or null | |
| buckets[].zones[].maxLength | integer or null | |
| buckets[].zones[].minLength | integer or null | |
| buckets[].zones[].avgWaitSeconds | number or null | |
| buckets[].zones[].avgServiceSeconds | number or null | |
| buckets[].zones[].entries | integer or null | |
| buckets[].zones[].leadEntries | integer or null | |
| buckets[].zones[].labelMinutes | object or null | |
| buckets[].zones[].labelMinutes.empty | integer | |
| buckets[].zones[].labelMinutes.low | integer | |
| buckets[].zones[].labelMinutes.moderate | integer | |
| buckets[].zones[].labelMinutes.high | integer | |
| buckets[].zones[].coverage | number or null | Share of the camera-seconds the bucket's lines or zones were expected to analyse that they did analyse (floored to 4 decimals); null when nothing was expected. |
| buckets[].zones[].status | one of: complete, partial, no_data | complete: coverage ≥ 0.9; partial: some but less; no_data: nothing analysed (every figure is null — a gap, never 0). |
| buckets[].zones[].analysedSeconds | integer | Camera-seconds analysed. |
| buckets[].zones[].expectedSeconds | integer | Camera-seconds expected (installed, signed off, line or zone drawn). |
| nextCursor | string or null | Pass as `cursor` to read the next page; null on the last page. |
Dwell
heatmap:readGET/api/v1/sites/{siteId}/dwell
Person-minutes and visits per dwell zone per bucket of site time (15 minutes, hour or day), each bucket with its coverage; a bucket with nothing analysed has null figures and status no_data — a gap, never 0. Buckets that start after the time of the read are not listed; the one containing it is inProgress. Paged by bucket: pass nextCursor as cursor with the same grain, from and to.
Parameters
| Name | In | Type | Description |
|---|---|---|---|
siteIdrequired | path | string | The site's id, from List sites. |
grainrequired | query | one of: 15m, hour, day | Bucket size in site time. |
fromrequired | query | string | Site-local date (inclusive) or RFC 3339 instant (buckets starting at or after it). |
torequired | query | string | Site-local date (inclusive) or RFC 3339 instant (buckets starting before it). Use the same form as from. |
cursor | query | string | nextCursor of the previous page. |
limit | query | integer | Buckets per page (default: a day of 15-minute buckets, a week of hours, a year of days; heatmap 24, at most 48). |
Request
curl "https://app.countport.com/api/v1/sites/s_3f9c1a2b4d5e6f70/dwell?grain=hour&from=2026-10-22&to=2026-10-22" \
-H "Authorization: Bearer $COUNTPORT_API_KEY"const res = await fetch("https://app.countport.com/api/v1/sites/s_3f9c1a2b4d5e6f70/dwell?grain=hour&from=2026-10-22&to=2026-10-22", {
headers: { Authorization: `Bearer ${process.env.COUNTPORT_API_KEY}` },
});
if (!res.ok) throw new Error(`${res.status}: ${(await res.json()).message}`);
const data = await res.json();import os
import requests
r = requests.get(
"https://app.countport.com/api/v1/sites/s_3f9c1a2b4d5e6f70/dwell",
params={"grain": "hour", "from": "2026-10-22", "to": "2026-10-22"},
headers={"Authorization": f"Bearer {os.environ['COUNTPORT_API_KEY']}"},
timeout=30,
)
r.raise_for_status()
data = r.json()Example answer
{
"site": {
"id": "s_3f9c1a2b4d5e6f70",
"name": "Main Street",
"timezone": "Europe/London"
},
"grain": "hour",
"zones": [
{
"zoneId": "zn_5H2N7D",
"deviceId": "dev_8a1e0c5b7d2f4936",
"cameraId": "cam_9XK4P1",
"name": "New arrivals",
"cameraName": "Checkout"
}
],
"buckets": [
{
"start": "2026-10-22T09:00:00Z",
"end": "2026-10-22T10:00:00Z",
"local": "2026-10-22T10:00+01:00",
"localDate": "2026-10-22",
"localStart": "10:00",
"localEnd": "11:00",
"utcOffset": "+01:00",
"fold": 0,
"inProgress": false,
"zones": [
{
"zoneId": "zn_5H2N7D",
"deviceId": "dev_8a1e0c5b7d2f4936",
"cameraId": "cam_9XK4P1",
"personMinutes": 186.5,
"visits": 64,
"coverage": 1,
"status": "complete",
"analysedSeconds": 3600,
"expectedSeconds": 3600
}
]
},
{
"start": "2026-10-22T10:00:00Z",
"end": "2026-10-22T11:00:00Z",
"local": "2026-10-22T11:00+01:00",
"localDate": "2026-10-22",
"localStart": "11:00",
"localEnd": "12:00",
"utcOffset": "+01:00",
"fold": 0,
"inProgress": false,
"zones": [
{
"zoneId": "zn_5H2N7D",
"deviceId": "dev_8a1e0c5b7d2f4936",
"cameraId": "cam_9XK4P1",
"personMinutes": 241.25,
"visits": 79,
"coverage": 1,
"status": "complete",
"analysedSeconds": 3600,
"expectedSeconds": 3600
}
]
}
],
"nextCursor": null
}Answer fields (32)
| Field | Type | Description |
|---|---|---|
| site | object | |
| site.id | string | |
| site.name | string | |
| site.timezone | string | IANA time zone every bucket is in. |
| grain | one of: 15m, hour, day | Bucket size in site time. |
| zones | array of object | |
| zones[].zoneId | string | |
| zones[].name | string | |
| zones[].deviceId | string | |
| zones[].cameraId | string | The device's own camera id. |
| zones[].cameraName | string | |
| buckets | array of object | |
| buckets[].start | string (date-time) | Bucket start (UTC), inclusive. |
| buckets[].end | string (date-time) | Bucket end (UTC), exclusive. |
| buckets[].local | string | Site-local start with its UTC offset. |
| buckets[].localDate | string | Site-local date of the start. |
| buckets[].localStart | string | Site-local wall-clock start. |
| buckets[].localEnd | string | Site-local wall-clock end ("24:00" at midnight). |
| buckets[].utcOffset | string | |
| buckets[].fold | one of: 0, 1 | 1 for the repeated wall-clock hour on the night the clocks go back. |
| buckets[].inProgress | boolean | The bucket contains the time of the read; its figures are still growing. |
| buckets[].zones | array of object | |
| buckets[].zones[].zoneId | string | |
| buckets[].zones[].deviceId | string | |
| buckets[].zones[].cameraId | string | The device's own camera id. |
| buckets[].zones[].personMinutes | number or null | Person-minutes spent in the zone. |
| buckets[].zones[].visits | integer or null | Dwell episodes that began in the bucket. |
| buckets[].zones[].coverage | number or null | Share of the camera-seconds the bucket's lines or zones were expected to analyse that they did analyse (floored to 4 decimals); null when nothing was expected. |
| buckets[].zones[].status | one of: complete, partial, no_data | complete: coverage ≥ 0.9; partial: some but less; no_data: nothing analysed (every figure is null — a gap, never 0). |
| buckets[].zones[].analysedSeconds | integer | Camera-seconds analysed. |
| buckets[].zones[].expectedSeconds | integer | Camera-seconds expected (installed, signed off, line or zone drawn). |
| nextCursor | string or null | Pass as `cursor` to read the next page; null on the last page. |
Heatmap
heatmap:readGET/api/v1/sites/{siteId}/heatmap
Person-minutes per grid cell of each heatmap zone (the camera's own grid over the full frame) per bucket of site time (15 minutes, hour or day), each bucket with its coverage; a bucket with nothing analysed has null figures and status no_data — a gap, never 0. Buckets that start after the time of the read are not listed; the one containing it is inProgress. Paged by bucket: pass nextCursor as cursor with the same grain, from and to. The range spans at most 31 days; at most 48 buckets per page.
Parameters
| Name | In | Type | Description |
|---|---|---|---|
siteIdrequired | path | string | The site's id, from List sites. |
grainrequired | query | one of: 15m, hour, day | Bucket size in site time. |
fromrequired | query | string | Site-local date (inclusive) or RFC 3339 instant (buckets starting at or after it). |
torequired | query | string | Site-local date (inclusive) or RFC 3339 instant (buckets starting before it). Use the same form as from. |
cursor | query | string | nextCursor of the previous page. |
limit | query | integer | Buckets per page (default: a day of 15-minute buckets, a week of hours, a year of days; heatmap 24, at most 48). |
Request
curl "https://app.countport.com/api/v1/sites/s_3f9c1a2b4d5e6f70/heatmap?grain=hour&from=2026-10-22&to=2026-10-22" \
-H "Authorization: Bearer $COUNTPORT_API_KEY"const res = await fetch("https://app.countport.com/api/v1/sites/s_3f9c1a2b4d5e6f70/heatmap?grain=hour&from=2026-10-22&to=2026-10-22", {
headers: { Authorization: `Bearer ${process.env.COUNTPORT_API_KEY}` },
});
if (!res.ok) throw new Error(`${res.status}: ${(await res.json()).message}`);
const data = await res.json();import os
import requests
r = requests.get(
"https://app.countport.com/api/v1/sites/s_3f9c1a2b4d5e6f70/heatmap",
params={"grain": "hour", "from": "2026-10-22", "to": "2026-10-22"},
headers={"Authorization": f"Bearer {os.environ['COUNTPORT_API_KEY']}"},
timeout=30,
)
r.raise_for_status()
data = r.json()Example answer
{
"site": {
"id": "s_3f9c1a2b4d5e6f70",
"name": "Main Street",
"timezone": "Europe/London"
},
"grain": "hour",
"zones": [
{
"zoneId": "zn_5H2N7D",
"deviceId": "dev_8a1e0c5b7d2f4936",
"cameraId": "cam_9XK4P1",
"name": "New arrivals",
"cameraName": "Checkout",
"polygon": [
{
"x": 0.12,
"y": 0.3
},
{
"x": 0.62,
"y": 0.3
},
{
"x": 0.62,
"y": 0.88
},
{
"x": 0.12,
"y": 0.88
}
],
"referenceWidth": 1920,
"referenceHeight": 1080
}
],
"buckets": [
{
"start": "2026-10-22T09:00:00Z",
"end": "2026-10-22T10:00:00Z",
"local": "2026-10-22T10:00+01:00",
"localDate": "2026-10-22",
"localStart": "10:00",
"localEnd": "11:00",
"utcOffset": "+01:00",
"fold": 0,
"inProgress": false,
"zones": [
{
"zoneId": "zn_5H2N7D",
"deviceId": "dev_8a1e0c5b7d2f4936",
"cameraId": "cam_9XK4P1",
"gridW": 32,
"gridH": 18,
"cells": [
[
200,
1.5
],
[
201,
4.25
],
[
233,
12.75
],
[
234,
9
],
[
266,
3.5
]
],
"totalPersonMinutes": 31,
"coverage": 1,
"status": "complete",
"analysedSeconds": 3600,
"expectedSeconds": 3600
}
]
}
],
"nextCursor": null
}Answer fields (39)
| Field | Type | Description |
|---|---|---|
| site | object | |
| site.id | string | |
| site.name | string | |
| site.timezone | string | IANA time zone every bucket is in. |
| grain | one of: 15m, hour, day | Bucket size in site time. |
| zones | array of object | |
| zones[].zoneId | string | |
| zones[].name | string | |
| zones[].deviceId | string | |
| zones[].cameraId | string | The device's own camera id. |
| zones[].cameraName | string | |
| zones[].polygon | array of object | The zone, normalised to the full frame (0..1, y down). |
| zones[].polygon[].x | number | |
| zones[].polygon[].y | number | |
| zones[].referenceWidth | number or null | |
| zones[].referenceHeight | number or null | |
| buckets | array of object | |
| buckets[].start | string (date-time) | Bucket start (UTC), inclusive. |
| buckets[].end | string (date-time) | Bucket end (UTC), exclusive. |
| buckets[].local | string | Site-local start with its UTC offset. |
| buckets[].localDate | string | Site-local date of the start. |
| buckets[].localStart | string | Site-local wall-clock start. |
| buckets[].localEnd | string | Site-local wall-clock end ("24:00" at midnight). |
| buckets[].utcOffset | string | |
| buckets[].fold | one of: 0, 1 | 1 for the repeated wall-clock hour on the night the clocks go back. |
| buckets[].inProgress | boolean | The bucket contains the time of the read; its figures are still growing. |
| buckets[].zones | array of object | |
| buckets[].zones[].zoneId | string | |
| buckets[].zones[].deviceId | string | |
| buckets[].zones[].cameraId | string | The device's own camera id. |
| buckets[].zones[].gridW | integer | |
| buckets[].zones[].gridH | integer | |
| buckets[].zones[].cells | array of [integer, number] | [row-major cell index, person-minutes] for every cell anyone was seen in, ascending. |
| buckets[].zones[].totalPersonMinutes | number or null | The zone's person-seconds in the bucket summed unrounded, then in person-minutes to 2 decimals (the engine's figure / 60; adding up the rounded `cells` can differ by up to 0.005 per cell); null when the zone was not analysed in the bucket. |
| buckets[].zones[].coverage | number or null | Share of the camera-seconds the bucket's lines or zones were expected to analyse that they did analyse (floored to 4 decimals); null when nothing was expected. |
| buckets[].zones[].status | one of: complete, partial, no_data | complete: coverage ≥ 0.9; partial: some but less; no_data: nothing analysed (every figure is null — a gap, never 0). |
| buckets[].zones[].analysedSeconds | integer | Camera-seconds analysed. |
| buckets[].zones[].expectedSeconds | integer | Camera-seconds expected (installed, signed off, line or zone drawn). |
| nextCursor | string or null | Pass as `cursor` to read the next page; null on the last page. |
Questions about the API?
Email info@countport.com, or ask the help desk in CountPort Cloud.