People Counting Software & API: Integration Guide for Developers
2026-08-29 16:07People counting software turns raw sensor events into occupancy, footfall and dwell metrics, and the integration between the two happens over a documented HTTP JSON interface rather than a proprietary SDK. A developer can pull counts with a signed POST request or receive them on a webhook, and the payload is the same either way.
The people counting API guide below covers the data model, the two integration patterns, authentication, and a first working request. The worked examples follow the interface exposed by Pyroglaux 3D stereo counters, and the general shape applies to most modern counting hardware.
What Does People Counting Software Actually Receive?
In a modern people counting system the sensor performs the counting on the device and emits structured events, so people counting software never processes video. Depth frames are analysed and discarded on the sensor itself.
A single crossing event carries four fields: a unique index for the tracked subject, a UNIX timestamp marking when the subject left the detection zone, an event type code, and a dwell duration in milliseconds.
| Field | Type | Meaning |
|---|---|---|
| idIndex | int | Unique index for the tracked subject within the session |
| timestamp | int64 | UNIX seconds at the moment the subject left the zone |
| eventType | int | 0 enter, 1 leave, 2 pass through, 3 re-entry, -1 invalid |
| stayTime | int | Dwell duration inside the zone, in milliseconds |
Source: Pyroglaux passenger flow HTTP interface specification, V2.1.5.
The four event types are the part most people counting software integrations get wrong. Treating every event as an entry double-counts anyone who walks past the door without coming in, and ignores the re-entry code that exists precisely to stop a returning shopper being counted as a new visitor.
How Does People Counting API Authentication Work?
Requests are signed rather than bearing a token in the header, using an MD5 digest of the sorted parameters concatenated with a shared service secret. The resulting digest is uppercased and sent in a Sign header.
The signing steps are fixed. Sort every request parameter in ASCII order, append the service secret agreed with the device, take the MD5 hex digest of that string, convert the digest to uppercase, and place the result in the Sign header alongside the standard JSON content type.
A signed people counting API request avoids storing a long-lived bearer token on a device that sits on a shop floor. A rotated service secret invalidates every previously captured request without a token revocation list.
Pull or Push: Which Integration Pattern Fits?
Pull suits small fleets and early development; push suits live dashboards and larger estates. Both return the same JSON body, so the parser written for one pattern works unchanged with the other.
When should people counting software poll the device?
People counting software should poll first, because polling is trivial to debug. A single curl command proves connectivity, authentication and payload shape before any application code exists.
The cost of polling is a reachable device. The server must be able to open a connection inward to each sensor, which means a VPN, a fixed address or a port mapping per device. Beyond roughly 50 devices that inventory becomes the dominant maintenance burden.
When should the sensor push instead?
Push configuration turns the sensor into the client, so the device only needs outbound network access. No inbound firewall rule and no per-device address book is required.
The device is given a destination URL through a configuration endpoint, after which crossing events post to that URL as they occur. Latency drops from the polling interval to near real time, which matters for occupancy limits and live queue displays.
How Do You Make the First Request?
Three people counter API endpoints cover almost every integration: live counts, historical totals, and the raw event list. The device listens on a fixed port and accepts RESTful POST requests with a JSON body.
| Purpose | Request body | Returns |
|---|---|---|
| Raw crossing events | startIndex, getQuantity | Event array plus a reply count |
| Historical totals | startTimestamp, endTimestamp | enter, leave, pass, return totals |
| Live tracking result | none | Current subjects inside the zone |
Source: Pyroglaux passenger flow HTTP interface specification, V2.1.5. Consult the current device documentation for exact paths, because endpoint names differ across firmware generations.
People counting software making a first request should ask for a small batch of events rather than a full day. Sending a start index of zero with a quantity of 100 returns at most 100 records, and the response reports how many records were actually available.
Every people counter API response carries a result object holding an error flag, a numeric code and a human-readable message. Checking the error flag before parsing the payload prevents an empty result being silently read as zero visitors.
What Are the Limits Worth Knowing Before Building?
On-device storage is a buffer, not a database. A counting device typically retains around three days of history, which is enough to survive a weekend network outage and not enough to serve as the system of record.
Three consequences follow for any people counting system built on these devices. Persist events into your own store on retrieval. Track the last successfully ingested index or timestamp so a restart resumes rather than restarts. Reconcile daily totals against the historical endpoint, because the aggregate query and the event list are computed separately on the device.
Clock drift deserves attention in any multi-site people counting system. Timestamps come from the device clock, so an unsynchronised sensor produces events that sort incorrectly against POS data. Configure a time server during commissioning rather than after the first mismatched report.
How Does the Data Reach a BI Tool?
Footfall data integration should store events raw and aggregate on read. Writing pre-aggregated hourly buckets into the warehouse is tempting and makes later questions about dwell time or re-entry unanswerable.
A workable minimum schema for footfall data integration is one row per event with device id, zone id, timestamp, event type and dwell. Hourly footfall, conversion against till data, and dwell distribution all derive from that single table with ordinary SQL.
People counting software that joins till transactions on device id and hour produces conversion rate directly. Retail teams applying the metric should read the retail metrics glossary for the definitions the dashboard will need.
Does People Counting Software Handle Personal Data?
A depth-based counting pipeline that transmits counts only does not process personal data, because no image and no identifier leaves the sensor. The payload described above contains an index scoped to a session, a timestamp and a duration.
Two design decisions keep people counting software in that position. Keep depth processing on the device rather than streaming frames to a server for analysis. Avoid joining the session index to any customer or employee record, since the join is what would create personal data where none existed.
Re-identification features that let people counting software deduplicate the same visitor across a day are available on some firmware, and those features change the analysis. Treat any deduplication capability as a separate privacy review rather than an automatic upgrade.
FAQ About People Counting Software and APIs
Is an SDK required to use a people counting API?
No, a signed HTTP POST with a JSON body is sufficient for the people counting API. Any language with an HTTP client and an MD5 function can integrate. Vendor SDKs wrap the same interface and are convenient rather than necessary, and avoiding an SDK keeps the integration portable across device generations.
How often should people counting software poll a device?
Every one to five minutes covers most reporting needs. Polling faster rarely helps because footfall is reported per crossing event and aggregated afterwards. Live occupancy displays are the exception, and those should use push rather than a faster poll.
What happens to counts during a network outage?
The device buffers events locally and serves the backlog once connectivity returns. Roughly three days of retention is typical. An ingester that tracks the last processed index recovers the gap automatically; an ingester that always requests the newest records loses the outage window permanently.
Can several systems call the same people counter API?
Yes, the pull interface is stateless and supports concurrent readers. Each caller supplies a start index or a time range, so a BI pipeline and a live dashboard can both query the same device. Push destinations are usually limited to a small number, so fan-out is better handled by a relay in your own infrastructure.
How is dwell time calculated?
Dwell arrives per event as stayTime in milliseconds, measured from entering to leaving the detection zone. Zone dwell is not the same as store dwell. Measuring how long a visitor stays in the store requires an entry event and a matching exit event, or a re-identification feature that links the two.
What should a people counting software integration test verify first?
Walk the doorway a known number of times and compare the count. Ten controlled passes in each direction validates direction assignment, event type mapping and timestamp handling in one exercise. Any mismatch at this stage is a configuration problem, not a code problem.
Next Steps
Start any footfall data integration with a single device, a polling script and ten controlled walk-throughs. Once the numbers match, decide whether the deployment needs push, and design the event store before scaling past one site.
Pyroglaux publishes the full HTTP interface specification with every device and does not gate integration behind a subscription. Browse the 3D counting sensor range or request the API documentation and a developer sample unit.