Skip to main content

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

  1. 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.
  2. 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.
  3. 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"

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"

Authentication

Send the key in a header, in either form:

Headers
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

ScopeNamed in CountPort CloudEndpoints
sites:readSitesList sites, Get a site
devices:readDevices and camera healthList devices with health, Get a device with health
footfall:readFootfallFootfall
occupancy:readOccupancyOccupancy, People inside now
queue:readQueueQueue
heatmap:readHeatmap and dwellDwell, 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.

One footfall bucket
{
  "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"]

Errors and limits

An error answers with its HTTP status and a JSON body. The code is stable; the message is for people.

403
{
  "code": "permission_denied",
  "message": "This API key does not have the devices:read scope."
}
StatusCodeWhen
400invalid_argumentInvalid parameters.
401unauthenticatedNo valid API key.
403permission_deniedThe key lacks the scope.
404not_foundNot found, or outside the key's tenant or site.
429rate_limitedOver the key's rate limit.
500internalSomething 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:read

GET/api/v1/sites

The sites the key may read, ordered by id.

Parameters

NameInTypeDescription
cursorquerystringnextCursor of the previous page.
limitqueryintegerItems per page (default 100).

Request

curl "https://app.countport.com/api/v1/sites" \
  -H "Authorization: Bearer $COUNTPORT_API_KEY"

Example answer

200 · SiteList
{
  "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)
FieldTypeDescription
sitesarray of object
sites[].idstring
sites[].namestring
sites[].timezonestring
sites[].groupIdstring or null
sites[].statusone of: active, archived
sites[].openingHoursobject or nullWeekly 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.weeklymap of array of object
sites[].openingHours.weekly.<key>[].openstring
sites[].openingHours.weekly.<key>[].closestring
sites[].openingHours.exceptionsmap of array of object
sites[].openingHours.exceptions.<key>[].openstring
sites[].openingHours.exceptions.<key>[].closestring
sites[].occupancyResetTimestringSite-local time occupancy restarts from 0 each day.
nextCursorstring or nullPass as `cursor` to read the next page; null on the last page.

Get a site

sites:read

GET/api/v1/sites/{siteId}

One site with its time zone, opening hours and occupancy reset.

Parameters

NameInTypeDescription
siteIdrequiredpathstringThe site's id, from List sites.

Request

curl "https://app.countport.com/api/v1/sites/s_3f9c1a2b4d5e6f70" \
  -H "Authorization: Bearer $COUNTPORT_API_KEY"

Example answer

200 · Site
{
  "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)
FieldTypeDescription
idstring
namestring
timezonestring
groupIdstring or null
statusone of: active, archived
openingHoursobject or nullWeekly 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.weeklymap of array of object
openingHours.weekly.<key>[].openstring
openingHours.weekly.<key>[].closestring
openingHours.exceptionsmap of array of object
openingHours.exceptions.<key>[].openstring
openingHours.exceptions.<key>[].closestring
occupancyResetTimestringSite-local time occupancy restarts from 0 each day.

Devices

List devices with health

devices:read

GET/api/v1/devices

Devices (store PCs) the key may read, ordered by id, with their health and their cameras' health.

Parameters

NameInTypeDescription
cursorquerystringnextCursor of the previous page.
limitqueryintegerItems per page (default 100).
sitequerystringOnly the devices of this site.

Request

curl "https://app.countport.com/api/v1/devices" \
  -H "Authorization: Bearer $COUNTPORT_API_KEY"

Example answer

200 · DeviceList
{
  "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)
FieldTypeDescription
devicesarray of object
devices[].idstring
devices[].namestring
devices[].siteIdstring or null
devices[].stateone of: awaiting_install, commissioned, retired, decommissioned
devices[].deviceClassone of: store_pc, camera
devices[].packageVersionstring or null
devices[].osstring or null
devices[].archstring or null
devices[].healthobject
devices[].health.statusone of: never_seen, online, degraded, offline, unpairedunpaired: the PC was unpaired on site and reports nothing until it is paired again.
devices[].health.lastSeenAtstring (date-time) or nullLast heartbeat or control-plane traffic (cloud clock).
devices[].health.connectedbooleanA control-plane connection is open now.
devices[].health.issuesarray of one of: engine_not_running, camera_not_streaming, backlog, rows_dropped, clock_offset, cpu_high, config_rejected
devices[].health.unsentMinutesinteger or nullMinutes of counts still in the device's outbox (last heartbeat).
devices[].health.clockOffsetMsinteger or null
devices[].camerasarray of object
devices[].cameras[].idstringThe device's own camera id (the cameraId in analytics).
devices[].cameras[].namestring
devices[].cameras[].enabledboolean
devices[].cameras[].stateone of: unknown, online, offline, error
devices[].cameras[].streamStateone of: connecting, streaming, backoff, disabled, error, or null
devices[].cameras[].decodeFpsnumber or null
devices[].cameras[].analysedFpsnumber or null
devices[].cameras[].lastMinuteCoverageSecondsinteger or null
devices[].cameras[].lastFrameAtstring (date-time) or nullLast decoded frame (device clock).
devices[].cameras[].reconnectsinteger or null
nextCursorstring or nullPass as `cursor` to read the next page; null on the last page.

Get a device with health

devices:read

GET/api/v1/devices/{deviceId}

One device with its health and its cameras' health.

Parameters

NameInTypeDescription
deviceIdrequiredpathstringThe device's id, from List devices.

Request

curl "https://app.countport.com/api/v1/devices/dev_8a1e0c5b7d2f4936" \
  -H "Authorization: Bearer $COUNTPORT_API_KEY"

Example answer

200 · Device
{
  "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)
FieldTypeDescription
idstring
namestring
siteIdstring or null
stateone of: awaiting_install, commissioned, retired, decommissioned
deviceClassone of: store_pc, camera
packageVersionstring or null
osstring or null
archstring or null
healthobject
health.statusone of: never_seen, online, degraded, offline, unpairedunpaired: the PC was unpaired on site and reports nothing until it is paired again.
health.lastSeenAtstring (date-time) or nullLast heartbeat or control-plane traffic (cloud clock).
health.connectedbooleanA control-plane connection is open now.
health.issuesarray of one of: engine_not_running, camera_not_streaming, backlog, rows_dropped, clock_offset, cpu_high, config_rejected
health.unsentMinutesinteger or nullMinutes of counts still in the device's outbox (last heartbeat).
health.clockOffsetMsinteger or null
camerasarray of object
cameras[].idstringThe device's own camera id (the cameraId in analytics).
cameras[].namestring
cameras[].enabledboolean
cameras[].stateone of: unknown, online, offline, error
cameras[].streamStateone of: connecting, streaming, backoff, disabled, error, or null
cameras[].decodeFpsnumber or null
cameras[].analysedFpsnumber or null
cameras[].lastMinuteCoverageSecondsinteger or null
cameras[].lastFrameAtstring (date-time) or nullLast decoded frame (device clock).
cameras[].reconnectsinteger or null

Analytics

Footfall

footfall:read

GET/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

NameInTypeDescription
siteIdrequiredpathstringThe site's id, from List sites.
grainrequiredqueryone of: 15m, hour, dayBucket size in site time.
fromrequiredquerystringSite-local date (inclusive) or RFC 3339 instant (buckets starting at or after it).
torequiredquerystringSite-local date (inclusive) or RFC 3339 instant (buckets starting before it). Use the same form as from.
cursorquerystringnextCursor of the previous page.
limitqueryintegerBuckets 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"

Example answer

200 · FootfallSeries · shortened
{
  "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)
FieldTypeDescription
siteobject
site.idstring
site.namestring
site.timezonestringIANA time zone every bucket is in.
grainone of: 15m, hour, dayBucket size in site time.
linesarray of objectEntrance-role lines expected or reporting in the page.
lines[].lineIdstring
lines[].namestring
lines[].deviceIdstring
lines[].cameraIdstringThe device's own camera id.
lines[].cameraNamestring
bucketsarray of object
buckets[].startstring (date-time)Bucket start (UTC), inclusive.
buckets[].endstring (date-time)Bucket end (UTC), exclusive.
buckets[].localstringSite-local start with its UTC offset.
buckets[].localDatestringSite-local date of the start.
buckets[].localStartstringSite-local wall-clock start.
buckets[].localEndstringSite-local wall-clock end ("24:00" at midnight).
buckets[].utcOffsetstring
buckets[].foldone of: 0, 11 for the repeated wall-clock hour on the night the clocks go back.
buckets[].inProgressbooleanThe bucket contains the time of the read; its figures are still growing.
buckets[].valueinteger or nullIN count of every entrance line together; null = not analysed.
buckets[].coveragenumber or nullShare 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[].statusone of: complete, partial, no_datacomplete: coverage ≥ 0.9; partial: some but less; no_data: nothing analysed (every figure is null — a gap, never 0).
buckets[].analysedSecondsintegerCamera-seconds analysed.
buckets[].expectedSecondsintegerCamera-seconds expected (installed, signed off, line or zone drawn).
buckets[].linesarray of object
buckets[].lines[].lineIdstring
buckets[].lines[].deviceIdstring
buckets[].lines[].cameraIdstringThe device's own camera id.
buckets[].lines[].valueinteger or null
buckets[].lines[].coveragenumber or nullShare 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[].statusone of: complete, partial, no_datacomplete: coverage ≥ 0.9; partial: some but less; no_data: nothing analysed (every figure is null — a gap, never 0).
buckets[].lines[].analysedSecondsintegerCamera-seconds analysed.
buckets[].lines[].expectedSecondsintegerCamera-seconds expected (installed, signed off, line or zone drawn).
nextCursorstring or nullPass as `cursor` to read the next page; null on the last page.

Occupancy

occupancy:read

GET/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

NameInTypeDescription
siteIdrequiredpathstringThe site's id, from List sites.
grainrequiredqueryone of: 15m, hourOccupancy is computed from quarter hours: 15m or hour.
fromrequiredquerystringSite-local date (inclusive) or RFC 3339 instant (buckets starting at or after it).
torequiredquerystringSite-local date (inclusive) or RFC 3339 instant (buckets starting before it). Use the same form as from.
cursorquerystringnextCursor of the previous page.
limitqueryintegerBuckets 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"

Example answer

200 · OccupancySeries · shortened
{
  "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)
FieldTypeDescription
siteobject
site.idstring
site.namestring
site.timezonestringIANA time zone every bucket is in.
grainone of: 15m, hour, dayBucket size in site time.
resetTimestring
bucketsarray of object
buckets[].startstring (date-time)Bucket start (UTC), inclusive.
buckets[].endstring (date-time)Bucket end (UTC), exclusive.
buckets[].localstringSite-local start with its UTC offset.
buckets[].localDatestringSite-local date of the start.
buckets[].localStartstringSite-local wall-clock start.
buckets[].localEndstringSite-local wall-clock end ("24:00" at midnight).
buckets[].utcOffsetstring
buckets[].foldone of: 0, 11 for the repeated wall-clock hour on the night the clocks go back.
buckets[].inProgressbooleanThe bucket contains the time of the read; its figures are still growing.
buckets[].valueinteger or nullPeople inside at the bucket's end; null when not analysed.
buckets[].peakinteger or null
buckets[].ininteger or null
buckets[].outinteger or null
buckets[].clampedintegerPeople dropped by the never-below-zero rule in the bucket.
buckets[].correctionsintegerManual corrections applied in the bucket.
buckets[].uncertainbooleanA quarter hour since the last reset was partial or not analysed.
buckets[].businessDatestring
buckets[].coveragenumber or nullShare 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[].statusone of: complete, partial, no_datacomplete: coverage ≥ 0.9; partial: some but less; no_data: nothing analysed (every figure is null — a gap, never 0).
buckets[].analysedSecondsintegerCamera-seconds analysed.
buckets[].expectedSecondsintegerCamera-seconds expected (installed, signed off, line or zone drawn).
nextCursorstring or nullPass as `cursor` to read the next page; null on the last page.

People inside now

occupancy:read

GET/api/v1/sites/{siteId}/occupancy/live

People inside now, from the minutes committed so far, with their freshness (stale after 6 minutes).

Parameters

NameInTypeDescription
siteIdrequiredpathstringThe 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"

Example answer

200 · OccupancyLive
{
  "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)
FieldTypeDescription
siteobject
site.idstring
site.namestring
site.timezonestringIANA time zone every bucket is in.
atstring (date-time)Time of the read.
valueinteger or null
statusone of: live, stale, no_data, no_entrances
businessDatestring
resetTimestring
resetAtstring (date-time)The last daily reset.
nextResetAtstring (date-time)The next daily reset.
asOfstring (date-time) or nullEnd of the newest minute every reporting entrance line delivered.
freshnessSecondsinteger or null
ininteger or null
outinteger or null
clampedPeopleinteger
correctionsinteger
uncertainboolean
uncertainSincestring (date-time) or nullFirst quarter hour since the reset that was partial or not analysed.
coveragenumber or null
entranceLinesinteger
linesReportinginteger

Queue

queue:read

GET/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

NameInTypeDescription
siteIdrequiredpathstringThe site's id, from List sites.
grainrequiredqueryone of: 15m, hour, dayBucket size in site time.
fromrequiredquerystringSite-local date (inclusive) or RFC 3339 instant (buckets starting at or after it).
torequiredquerystringSite-local date (inclusive) or RFC 3339 instant (buckets starting before it). Use the same form as from.
cursorquerystringnextCursor of the previous page.
limitqueryintegerBuckets 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"

Example answer

200 · QueueSeries · shortened
{
  "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)
FieldTypeDescription
siteobject
site.idstring
site.namestring
site.timezonestringIANA time zone every bucket is in.
grainone of: 15m, hour, dayBucket size in site time.
zonesarray of object
zones[].zoneIdstring
zones[].namestring
zones[].deviceIdstring
zones[].cameraIdstringThe device's own camera id.
zones[].cameraNamestring
zones[].capacitynumber or null
zones[].totalCashiersinteger or null
bucketsarray of object
buckets[].startstring (date-time)Bucket start (UTC), inclusive.
buckets[].endstring (date-time)Bucket end (UTC), exclusive.
buckets[].localstringSite-local start with its UTC offset.
buckets[].localDatestringSite-local date of the start.
buckets[].localStartstringSite-local wall-clock start.
buckets[].localEndstringSite-local wall-clock end ("24:00" at midnight).
buckets[].utcOffsetstring
buckets[].foldone of: 0, 11 for the repeated wall-clock hour on the night the clocks go back.
buckets[].inProgressbooleanThe bucket contains the time of the read; its figures are still growing.
buckets[].zonesarray of object
buckets[].zones[].zoneIdstring
buckets[].zones[].deviceIdstring
buckets[].zones[].cameraIdstringThe device's own camera id.
buckets[].zones[].avgLengthnumber or null
buckets[].zones[].maxLengthinteger or null
buckets[].zones[].minLengthinteger or null
buckets[].zones[].avgWaitSecondsnumber or null
buckets[].zones[].avgServiceSecondsnumber or null
buckets[].zones[].entriesinteger or null
buckets[].zones[].leadEntriesinteger or null
buckets[].zones[].labelMinutesobject or null
buckets[].zones[].labelMinutes.emptyinteger
buckets[].zones[].labelMinutes.lowinteger
buckets[].zones[].labelMinutes.moderateinteger
buckets[].zones[].labelMinutes.highinteger
buckets[].zones[].coveragenumber or nullShare 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[].statusone of: complete, partial, no_datacomplete: coverage ≥ 0.9; partial: some but less; no_data: nothing analysed (every figure is null — a gap, never 0).
buckets[].zones[].analysedSecondsintegerCamera-seconds analysed.
buckets[].zones[].expectedSecondsintegerCamera-seconds expected (installed, signed off, line or zone drawn).
nextCursorstring or nullPass as `cursor` to read the next page; null on the last page.

Dwell

heatmap:read

GET/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

NameInTypeDescription
siteIdrequiredpathstringThe site's id, from List sites.
grainrequiredqueryone of: 15m, hour, dayBucket size in site time.
fromrequiredquerystringSite-local date (inclusive) or RFC 3339 instant (buckets starting at or after it).
torequiredquerystringSite-local date (inclusive) or RFC 3339 instant (buckets starting before it). Use the same form as from.
cursorquerystringnextCursor of the previous page.
limitqueryintegerBuckets 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"

Example answer

200 · DwellSeries · shortened
{
  "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)
FieldTypeDescription
siteobject
site.idstring
site.namestring
site.timezonestringIANA time zone every bucket is in.
grainone of: 15m, hour, dayBucket size in site time.
zonesarray of object
zones[].zoneIdstring
zones[].namestring
zones[].deviceIdstring
zones[].cameraIdstringThe device's own camera id.
zones[].cameraNamestring
bucketsarray of object
buckets[].startstring (date-time)Bucket start (UTC), inclusive.
buckets[].endstring (date-time)Bucket end (UTC), exclusive.
buckets[].localstringSite-local start with its UTC offset.
buckets[].localDatestringSite-local date of the start.
buckets[].localStartstringSite-local wall-clock start.
buckets[].localEndstringSite-local wall-clock end ("24:00" at midnight).
buckets[].utcOffsetstring
buckets[].foldone of: 0, 11 for the repeated wall-clock hour on the night the clocks go back.
buckets[].inProgressbooleanThe bucket contains the time of the read; its figures are still growing.
buckets[].zonesarray of object
buckets[].zones[].zoneIdstring
buckets[].zones[].deviceIdstring
buckets[].zones[].cameraIdstringThe device's own camera id.
buckets[].zones[].personMinutesnumber or nullPerson-minutes spent in the zone.
buckets[].zones[].visitsinteger or nullDwell episodes that began in the bucket.
buckets[].zones[].coveragenumber or nullShare 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[].statusone of: complete, partial, no_datacomplete: coverage ≥ 0.9; partial: some but less; no_data: nothing analysed (every figure is null — a gap, never 0).
buckets[].zones[].analysedSecondsintegerCamera-seconds analysed.
buckets[].zones[].expectedSecondsintegerCamera-seconds expected (installed, signed off, line or zone drawn).
nextCursorstring or nullPass as `cursor` to read the next page; null on the last page.

Heatmap

heatmap:read

GET/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

NameInTypeDescription
siteIdrequiredpathstringThe site's id, from List sites.
grainrequiredqueryone of: 15m, hour, dayBucket size in site time.
fromrequiredquerystringSite-local date (inclusive) or RFC 3339 instant (buckets starting at or after it).
torequiredquerystringSite-local date (inclusive) or RFC 3339 instant (buckets starting before it). Use the same form as from.
cursorquerystringnextCursor of the previous page.
limitqueryintegerBuckets 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"

Example answer

200 · HeatmapSeries · shortened
{
  "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)
FieldTypeDescription
siteobject
site.idstring
site.namestring
site.timezonestringIANA time zone every bucket is in.
grainone of: 15m, hour, dayBucket size in site time.
zonesarray of object
zones[].zoneIdstring
zones[].namestring
zones[].deviceIdstring
zones[].cameraIdstringThe device's own camera id.
zones[].cameraNamestring
zones[].polygonarray of objectThe zone, normalised to the full frame (0..1, y down).
zones[].polygon[].xnumber
zones[].polygon[].ynumber
zones[].referenceWidthnumber or null
zones[].referenceHeightnumber or null
bucketsarray of object
buckets[].startstring (date-time)Bucket start (UTC), inclusive.
buckets[].endstring (date-time)Bucket end (UTC), exclusive.
buckets[].localstringSite-local start with its UTC offset.
buckets[].localDatestringSite-local date of the start.
buckets[].localStartstringSite-local wall-clock start.
buckets[].localEndstringSite-local wall-clock end ("24:00" at midnight).
buckets[].utcOffsetstring
buckets[].foldone of: 0, 11 for the repeated wall-clock hour on the night the clocks go back.
buckets[].inProgressbooleanThe bucket contains the time of the read; its figures are still growing.
buckets[].zonesarray of object
buckets[].zones[].zoneIdstring
buckets[].zones[].deviceIdstring
buckets[].zones[].cameraIdstringThe device's own camera id.
buckets[].zones[].gridWinteger
buckets[].zones[].gridHinteger
buckets[].zones[].cellsarray of [integer, number][row-major cell index, person-minutes] for every cell anyone was seen in, ascending.
buckets[].zones[].totalPersonMinutesnumber or nullThe 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[].coveragenumber or nullShare 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[].statusone of: complete, partial, no_datacomplete: coverage ≥ 0.9; partial: some but less; no_data: nothing analysed (every figure is null — a gap, never 0).
buckets[].zones[].analysedSecondsintegerCamera-seconds analysed.
buckets[].zones[].expectedSecondsintegerCamera-seconds expected (installed, signed off, line or zone drawn).
nextCursorstring or nullPass 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.

Talk to us ›