Skip to main content

People Counting & Traffic Analytics API

Viewtron AI cameras include built-in people counting that runs entirely on the camera hardware — no cloud service or external software required. When a person, vehicle, or motorcycle crosses a virtual counting line or enters a defined counting area, the camera sends an HTTP POST webhook to your server with the event data, including a full-frame overview image, a cropped image of the counted target, and the boundary or line coordinates that were crossed.

There are two counting methods available, each suited to different use cases. Line counting tracks objects crossing a virtual line and classifies each crossing as an entrance or exit. Area counting tracks objects entering a defined polygon region. Both methods include images with every event, and line counting also supports a polling endpoint to query cumulative entrance/exit statistics without webhooks.

What You Can Build​

  • Retail foot traffic analytics — count customers entering and exiting a store entrance, track hourly and daily patterns
  • Building occupancy monitoring — maintain a real-time occupancy count by tracking entrances minus exits
  • Parking lot capacity — count vehicles entering and exiting a lot, display available spaces
  • Queue monitoring — count people entering a service area and detect when queue length exceeds a threshold
  • Bi-directional traffic analysis — use the line counting direction to separate inbound vs outbound foot traffic
  • Multi-zone analytics — deploy area counting across different store sections to identify high-traffic areas

How It Works​

  1. Configure a counting line or area on the camera — draw a virtual line with a direction arrow, or define a polygon region
  2. Enable HTTP POST webhooks — point the camera or NVR at your server's IP and port
  3. Your server receives XML when a count event occurs — the POST includes the counting method, target coordinates, boundary geometry, and base64 images
  4. Parse the event using the Viewtron Python SDK (pip install viewtron) or Node.js SDK
  5. Track counts and take action — maintain running entrance/exit totals, save images, log to CSV, trigger alerts at thresholds

Counting Methods​

Line Counting (targetCountingByLine / PASSLINECOUNT)​

Objects are counted when they cross a virtual line drawn on the camera view. The line has a direction arrow — crossings in the direction of the arrow are counted as entrances, and crossings against it are counted as exits. This is the most common method for doorways, hallways, and gates.

FieldDescription
smartTypePASSLINECOUNT (IPC) or targetCountingByLine (NVR)
targetTypeperson, car, or motor
boundarytripwire — indicates a line crossing event
directionLineStart and end point coordinates of the counting line
rectBounding box of the target (may be all zeros for line counting)
eventId / targetIdUnique IDs for the event and tracked target
sourceBase64DataFull-frame JPEG image (base64 encoded)
targetBase64DataCropped target JPEG image (base64 encoded)
currentTimeDetection timestamp

Area Counting (targetCountingByArea / TRAFFIC)​

Objects are counted when they enter a defined polygon region. This is useful for open areas, intersections, or zones where a single line crossing is not practical.

FieldDescription
smartTypeTRAFFIC (IPC) or targetCountingByArea (NVR)
targetTypeperson, car, or motor
boundaryarea — indicates an area entry event
pointGroupPolygon coordinates defining the counting area
rectBounding box of the detected target (x1, y1, x2, y2)
eventId / targetIdUnique IDs for the event and tracked target
sourceBase64DataFull-frame JPEG image (base64 encoded)
targetBase64DataCropped target JPEG image (base64 encoded)
currentTimeDetection timestamp

Parsing Counting Events​

The simplest way to receive counting events. The SDK's ViewtronServer handles HTTP connections, keepalives, XML parsing, and version detection — you just write the callback:

pip install viewtron
from viewtron import ViewtronServer
import os

IMG_DIR = "images"
os.makedirs(IMG_DIR, exist_ok=True)

entrance_count = 0
area_count = 0

def on_event(event, client_ip):
    global entrance_count, area_count
    if event.category != "counting":
        return

    print(f"Counting event from {client_ip}")
    print(f"  Type: {event.get_alarm_type()} ({event.get_alarm_description()})")

    # Track running totals
    entrance_count += 1
    print(f"  Running total: {entrance_count}")

    overview = event.get_source_image_bytes()
    if overview:
        with open(f"{IMG_DIR}/{event.get_time_stamp()}-count-overview.jpg", "wb") as f:
            f.write(overview)

server = ViewtronServer(port=5002, on_event=on_event)
server.serve_forever()

See the Python SDK reference for the full list of methods and event classes.

Polling Statistics (v2.0 IPC Only)​

For line counting, you can query the camera's cumulative entrance/exit counts directly without webhooks using the GetPassLineCountStatistics endpoint. This is useful for periodic polling or dashboard displays.

Request:

GET http://<camera-ip>/GetPassLineCountStatistics

Response:

<?xml version="1.0" encoding="utf-8"?>
<config xmlns="http://www.ipc.com/ver10" version="2.0.0">
  <entranceCount>
    <person type="uint32">0</person>
    <car type="uint32">0</car>
    <bike type="uint32">0</bike>
  </entranceCount>
  <exitCount>
    <person type="uint32">0</person>
    <car type="uint32">0</car>
    <bike type="uint32">0</bike>
  </exitCount>
</config>

This returns separate entrance and exit counts for each object type (person, car, bike). The counts are cumulative since the camera was last reset.

tip

Use GetPassLineCountStatistics for simple dashboard displays where you only need current totals. Use webhook events when you need per-event images, timestamps, and real-time processing.

Relevant API Endpoints​

EndpointPurposeReference
GetSmartPassLineCountConfigRead line counting zone configurationPass Line Count Config
GetPassLineCountStatisticsQuery current entrance/exit counts (v2.0 IPC)Pass Line Count Config
SetHttpPostConfigConfigure webhook destinationWebhook Config
GetAlarmStatusPoll current alarm stateAlarm Status

Integrations​

Viewtron people counting also integrates with automation platforms via published packages:

PlatformPackageWhat It Does
Home Assistantviewtron-home-assistantPeople/vehicle counting as native HA sensors for occupancy tracking
Node-REDnode-red-contrib-viewtronCounting events direct to Node-RED flows — no middleware needed

Questions & Development Inquiries​

Mike Haldas is available for questions, consultation, and custom software development for Viewtron API related projects. Email details about your project to mike@viewtron.com.