Skip to main content

Loitering Detection Camera API

Viewtron AI security cameras include built-in loitering detection that runs entirely on the camera hardware — no cloud service or external AI software required. When a person or vehicle remains in a defined zone beyond a configurable time threshold, the camera sends an HTTP POST webhook to your server with the detection event data, including a full-frame overview image and a cropped image of the loitering target.

Loitering detection differs from intrusion detection in that it measures dwell time — an intrusion event fires immediately when a target enters a zone, while a loitering event only fires after the target has remained in the zone for longer than the configured time threshold. This makes loitering detection ideal for identifying suspicious behavior where brief presence is normal but prolonged presence is not. All Viewtron IP cameras and NVRs are NDAA compliant.

What You Can Build​

  • ATM security monitoring — alert when someone lingers near an ATM beyond a normal transaction time
  • Retail loss prevention — detect customers dwelling in high-theft areas for extended periods
  • Restricted area monitoring — identify unauthorized individuals loitering near secure entrances, server rooms, or utility areas
  • Public safety alerts — monitor bus stops, park benches, or public spaces for extended occupancy
  • Loading dock security — detect unauthorized vehicles dwelling in delivery zones beyond permitted times
  • Progressive response — combine with active deterrent to escalate from light activation to siren based on dwell duration

How It Works​

  1. Configure a loitering zone on the camera — define a polygon region and set the dwell time threshold (seconds)
  2. Enable object filters — select which target types to monitor (person, vehicle, or both)
  3. Enable HTTP POST webhooks — point the camera at your server's IP and port
  4. Your server receives XML when loitering is detected — the POST includes alarm type, zone boundary, target bounding box, and base64 images
  5. Parse the event using the Viewtron Python SDK (pip install viewtron) or Node.js SDK
  6. Take action — save images, log to CSV, send alerts, trigger deterrent actions

Event Data Included​

Each loitering detection webhook POST contains:

FieldDescription
smartTypeLOITER (IPC loitering detection)
boundaryPolygon coordinates of the loitering zone
rectBounding box of the loitering target
eventId / targetIdUnique IDs for the event and tracked target
statusSMART_START, SMART_PROCEDURE, or SMART_STOP
sourceBase64DataFull-frame JPEG image (base64 encoded)
targetBase64DataCropped target JPEG image (base64 encoded)
currentTimeDetection timestamp

Parsing Loitering Events​

The simplest way to receive loitering 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)

def on_event(event, client_ip):
    if event.category != "intrusion":
        return
    # Loitering events use the intrusion category with LOITER alarm type
    if event.get_alarm_type() not in ("LOITER", "loitering"):
        return
    print(f"Loitering detected from {client_ip}")
    print(f"  Type: {event.get_alarm_description()}")
    print(f"  Time: {event.get_time_stamp_formatted()}")

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

    target = event.get_target_image_bytes()
    if target:
        with open(f"{IMG_DIR}/{event.get_time_stamp()}-loitering-target.jpg", "wb") as f:
            f.write(target)

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.

Relevant API Endpoints​

EndpointPurposeReference
GetSmartLoiteringConfigRead loitering detection zone and time threshold configurationLoitering Detection Config
SetHttpPostConfigConfigure webhook destinationWebhook Config
GetAlarmStatusPoll current alarm stateAlarm Status

Integrations​

Viewtron loitering detection also integrates with automation platforms via published packages:

PlatformPackageWhat It Does
Home Assistantviewtron-home-assistantLoitering events as native HA sensors — automate deterrents, alerts, notifications
Node-REDnode-red-contrib-viewtronLoitering 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.