Skip to main content

License Plate Recognition Camera API (LPR/ALPR)

Viewtron AI security cameras include built-in license plate recognition (LPR/ALPR) that runs entirely on the camera hardware — no cloud service, external software, or third-party LPR engine required. When a vehicle passes through the camera's detection zone, the camera reads the license plate and sends an HTTP POST webhook to your server with the plate number, a cropped plate image, an overview image, and, depending on firmware, vehicle attributes including type, color, brand, and model. LPR-IP4 firmware 5.3.1 sends vehicle attributes in the camera's own post (carAttr), and the NVR v2.0 format carries them as carAttribute.

The API also supports managing an on-camera plate database with whitelist and blacklist entries, enabling automated gate access control without any middleware. Plates can be added with date ranges and owner information. The camera includes a Wiegand output for direct integration with gate controllers and access control panels. All Viewtron IP cameras and NVRs are NDAA compliant.

What You Can Build​

  • Automated gate access control — open gates and barriers when whitelisted plates are detected, using Wiegand output or webhook-triggered relay
  • Vehicle access logs — record every plate read with timestamp, plate image, and authorization status for parking garages, gated communities, or corporate campuses
  • Visitor management systems — pre-register expected visitor plates with date ranges using AddLicensePlates, automatically grant access on arrival
  • Blacklist alerting — receive instant notifications when a blacklisted plate is detected on property
  • Fleet tracking — monitor arrival/departure times for company vehicles across multiple camera locations
  • Law enforcement integration — feed plate reads into stolen vehicle databases or BOLO systems in real time
  • Parking enforcement — detect unauthorized vehicles and trigger alerts or record violations with plate crop images

How It Works​

  1. Install an LPR camera at the vehicle entry point — position the camera to capture plates at the correct angle and distance
  2. Configure LPR detection on the camera — set the plate region (U.S.A, Canada, Europe, etc.), sensitivity, and detection zone
  3. Enable HTTP POST webhooks — point the camera or NVR at your server's IP and port
  4. Manage the plate database (optional) — add plates to the whitelist or blacklist using the AddLicensePlates API with owner info
  5. Your server receives XML when a plate is read — the POST includes the plate number, plate group status, plate crop image, and vehicle attributes
  6. Parse the event using the Viewtron Python SDK (pip install viewtron) or raw XML parsing in any language
  7. Take action — log the plate read, trigger a gate relay, send alerts, or update your database

Event Data​

Each LPR webhook POST contains the fields below. Field names differ between a camera posting directly (IPC v1.x) and an NVR (v2.0), and some fields depend on firmware. See Firmware Differences.

FieldDescription
smartTypeIPC: VEHICE or VEHICLE, depending on firmware. NVR: vehicle
plateNumber / licensePlateNumberDetected plate text (e.g., JP116D)
vehicleDirectIPC: approach or away
PlateConfidenceIPC: confidence in the count attribute, 0-10000 (count="9900" = 99%)
vehicleListTypeIPC: whiteList or blackList on firmware 5.3.1, absent if the plate is on no list. Never sent on firmware 5.1.x. temporaryList is documented but not yet confirmed in a captured post.
licensePlateMatchInfo/groupNameNVR: user-defined group name (e.g., "Whitelist", "Residents"), or absent if not in database. Not yet confirmed in a captured post.
plateColor / licensePlateAttribute/colorPlate color. IPC: a numeric code in the count attribute. NVR: a color name
carAttr/type / carAttribute/carTypeVehicle type: saloon car (IPC 5.3.1), or sedan, suv, mpv, truck, etc. (NVR)
carAttr/color / carAttribute/colorVehicle color
carAttr/brand / carAttribute/brandVehicle brand: GMC, Ford, Toyota, etc.
carAttr/model / carAttribute/modelVehicle model: GMC_SAVANA, etc.
rect / corner pointsNVR: plate bounding box (x1, y1, x2, y2). IPC: leftTop, rightTop, leftBottom, rightBottom, normalized 0-10000
targetBase64DataCropped plate JPEG image (base64 encoded, ~10-20 KB)
Overview imageFull-frame JPEG, base64 encoded. IPC: listInfo item 0 targetBase64Data (about 760 KB of base64 text in an LPR-IP4 firmware 5.3.1 post; there is no sourceDataInfo). NVR: sourceBase64Data
currentTimeDetection timestamp, Unix microseconds from the device clock

Decode the base64 text itself. The declared targetBase64Length did not match the actual text on LPR-IP4 firmware 5.3.1.

Parsing LPR Events​

The simplest way to receive LPR 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 != "lpr":
        return

    plate = event.get_plate_number()
    group = event.get_plate_group()  # "whiteList", NVR group name, or ""
    print(f"Plate: {plate} | Group: {group or 'Unknown'}")

    # Save plate crop image
    plate_jpg = event.get_target_image_bytes()
    if plate_jpg:
        with open(f"{IMG_DIR}/{plate}.jpg", "wb") as f:
            f.write(plate_jpg)

    # NVR v2.0 includes vehicle attributes
    if event.get_alarm_type() == "vehicle":
        print(f"  Vehicle: {event.get_car_brand()} {event.get_car_model()}")

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.

Managing the Plate Database​

The LPR camera maintains an on-device plate database. Use the Viewtron Python SDK or the raw API to manage plates:

from viewtron import ViewtronCamera

camera = ViewtronCamera("192.168.0.20", "admin", "password")

# Add a plate to the allow list
camera.add_plate("ABC1234")

# Query the database
plates = camera.get_plates()
for plate in plates:
    print(plate["plate_number"], plate["owner"])

# Update plate details
camera.modify_plate("ABC1234", owner="Mike", telephone="555-1234")

# Remove a plate
camera.delete_plate("ABC1234")

See the LPR Config API reference for the complete plate database API including ModifyLicensePlate and DeleteLicensePlate.

Relevant API Endpoints​

EndpointPurposeReference
GetSmartVehicleConfigRead LPR detection settings (sensitivity, region, dedup mode)LPR Config
AddLicensePlatesAdd plates to the databaseLPR Config
GetLicensePlatesQuery the plate database with paginationLPR Config
ModifyLicensePlateUpdate plate details (owner, phone)LPR Config
DeleteLicensePlateRemove a plate from the databaseLPR Config
SetHttpPostConfigConfigure webhook destinationWebhook Config
GetAlarmStatusPoll current alarm stateAlarm Status
Wiegand Output for Gate Access

Viewtron LPR cameras include a Wiegand output that sends the plate number directly to gate controllers and access control panels. This works independently of the HTTP API — the camera can simultaneously send Wiegand signals to a gate controller and HTTP POST webhooks to your software.

Integrations​

Viewtron LPR cameras also integrate with automation platforms via published packages:

PlatformPackageWhat It Does
Home Assistantviewtron-home-assistantPlate reads + images as native HA sensors via MQTT — automate gates, lights, alerts
Node-REDnode-red-contrib-viewtronPlate reads direct to Node-RED flows — no middleware needed

Video Guides​

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.