Nodeflux Central
Tracking

API Reference: Tracking

Endpoint di balik tampilan pelacakan Face Search dan Plate Search: riwayat event per face_id, riwayat event per nomor plat, dan pencarian plat teragregasi.

← Kembali ke Tracking

Panduan operator: melacak pergerakan wajah dan plat dari Face Search, Plate Search, dan Events.

Otentikasi

API key untuk integrasi, Bearer token untuk sesi pengguna, dan otentikasi WebSocket.

Semua endpoint memerlukan otentikasi. Untuk integrasi, kirim header X-Api-Key: <key> di setiap request tanpa header Authorization. Bearer token (Authorization: Bearer <access_token>, berlaku 30 menit) hanya untuk aplikasi yang menampilkan login Lenz ke penggunanya sendiri dan wajib menyertakan X-Integration-Signature. Basis URL mengikuti variabel lingkungan VITE_API_URL yang dikonfigurasi pada instalasi Lenz. Lihat Otentikasi untuk memilih jalur yang tepat.

Ketiga endpoint bekerja pada data event yang sudah tersimpan di database Lenz, bukan pada stream langsung. Identitas yang dilacak harus sama persis dengan nilai pada event: face_id dari analitik Face Recognition, atau nomor plat sebagaimana dibaca oleh LPR. Nilai timestamp_from dan timestamp_to wajib dikirim dalam format ISO 8601 beserta offset zona waktu (misalnya 2026-09-15T00:00:00+07:00).

Pelacakan Wajah

Satu endpoint mengembalikan semua event Face Recognition, berstatus KNOWN maupun UNKNOWN, yang membawa face_id yang diminta. Endpoint ini hanya memerlukan sesi atau API key yang valid; izin resource events tidak diperiksa, tetapi setiap panggilan dicatat di audit log.

Riwayat Pergerakan Wajah

GET
/api/events/face-related

Authorization

bearerAuth
AuthorizationBearer <token>

In: header

Query Parameters

face_id*string

Face ID yang dilacak, persis seperti nilai pipeline_data.face_id pada event. Bila kosong, hasil selalu kosong.

timestamp_from*string

Batas awal rentang waktu (ISO 8601 dengan offset). Wajib: bila kosong query gagal dan respons 500.

Formatdate-time
timestamp_to*string

Batas akhir rentang waktu (ISO 8601 dengan offset). Wajib: bila kosong query gagal dan respons 500.

Formatdate-time
limit?integer

Jumlah maksimum event setelah deduplikasi. Default 10 (UI memakai 1000). Harus berupa angka; nilai bukan angka menghasilkan 500.

Default10
timezone?string

Diterima untuk kompatibilitas dengan klien Lenz, tetapi saat ini tidak diterapkan: timestamp selalu dikembalikan dalam UTC.

disable_base64_image?boolean

Jika true, primary_image/secondary_image (Base64) dihilangkan dan diganti primary_image_url/secondary_image_url. Default false; UI Lenz selalu mengirim true.

Defaultfalse
include_embeddings?boolean

Jika false, key embedding dibuang dari pipeline_data. Default true demi kompatibilitas; UI Lenz mengirim false karena embedding tidak diperlukan untuk tampilan.

Defaulttrue

Response Body

application/json

application/json

application/json

curl -X GET "https://lenz.example.com/api/events/face-related?face_id=abc123def456&timestamp_from=2026-09-08T00%3A00%3A00%2B07%3A00&timestamp_to=2026-09-15T23%3A59%3A59%2B07%3A00&limit=1000&timezone=Asia%2FJakarta&disable_base64_image=true&include_embeddings=false"
{  "ok": true,  "message": "successfully get data face related event",  "data": [    {      "id": 1001,      "analytic_id": "NFV4-FR",      "node_num": 1,      "stream_id": "stream-camera-lobby",      "stream_latitude": -6.2088,      "stream_longitude": 106.8456,      "primary_image_url": "/api/event/image?event_id=c0ffee12-3456-4789-abcd-ef0123456789&type=primary",      "secondary_image_url": "/api/event/image?event_id=c0ffee12-3456-4789-abcd-ef0123456789&type=secondary",      "label": "Budi Santoso",      "result": "abc123def456",      "location": "Lobby Utama",      "status": "KNOWN",      "logic": "MATCH",      "timestamp": "2026-09-15T01:23:11Z",      "pipeline_event_id": "c0ffee12-3456-4789-abcd-ef0123456789",      "pipeline_data": {        "event_id": "c0ffee12-3456-4789-abcd-ef0123456789",        "face_id": "abc123def456",        "attributes": {          "recognition": {            "label": "Budi Santoso",            "face_id": "abc123def456",            "confidence": 0.92          }        }      }    }  ]}
{  "ok": false,  "code": "not-authenticate",  "errors": [],  "message": "Authorization not found"}
{  "ok": false,  "code": "internal-server-error",  "errors": [],  "message": "strconv.Atoi: parsing \"abc\": invalid syntax"}

Pelacakan Plat

Dua endpoint yang bekerja berurutan: pencarian teragregasi menemukan nomor plat dari potongan teks, lalu riwayat pergerakan mengambil setiap deteksi plat yang dipilih. Keduanya memerlukan izin pada resource events.

Alur tipikal: panggil GET /api/events/search/plates?q=1234&timestamp_from=...&timestamp_to=... untuk menemukan plat yang cocok beserta detection_count dan last_seen, lalu gunakan plate_number dari hasil tersebut apa adanya sebagai parameter GET /api/events/plate-related. Nomor plat harus dikirim persis seperti hasil pembacaan LPR (huruf kapital, umumnya tanpa spasi).

Pencarian Plat Teragregasi

GET
/api/events/search/plates

Authorization

bearerAuth
AuthorizationBearer <token>

In: header

Query Parameters

q*string

Potongan nomor plat yang dicari (substring, tidak peka huruf besar-kecil). Wajib diisi; string kosong ditolak dengan 400.

timestamp_from*string

Batas awal rentang waktu (ISO 8601 dengan offset). Wajib diisi.

Formatdate-time
timestamp_to*string

Batas akhir rentang waktu (ISO 8601 dengan offset). Wajib diisi.

Formatdate-time
limit?integer

Jumlah maksimum plat unik yang dikembalikan. Default 20; nilai di atas 100 dipangkas menjadi 100.

Default20
Rangevalue <= 100
timezone?string

Zona waktu IANA untuk menyajikan first_seen dan last_seen (contoh: Asia/Jakarta). Default UTC; nilai yang tidak dikenal diabaikan dan UTC dipakai.

Response Body

application/json

application/json

application/json

application/json

curl -X GET "https://lenz.example.com/api/events/search/plates?q=1234&timestamp_from=2026-09-08T00%3A00%3A00%2B07%3A00&timestamp_to=2026-09-15T23%3A59%3A59%2B07%3A00&limit=20&timezone=Asia%2FJakarta"
{  "ok": true,  "message": "successfully searched plates",  "data": [    {      "plate_number": "B1234XYZ",      "event_id": "7f3c1a2e-4b8d-4e1f-9a6b-2c5d8e9f0a11",      "first_seen": "2026-09-10T07:15:00+07:00",      "last_seen": "2026-09-15T18:42:00+07:00",      "detection_count": 7    },    {      "plate_number": "D1234AB",      "event_id": "0a1b2c3d-4e5f-4a6b-8c9d-0e1f2a3b4c5d",      "first_seen": "2026-09-12T09:00:00+07:00",      "last_seen": "2026-09-12T09:00:00+07:00",      "detection_count": 1    }  ]}
{  "ok": false,  "code": "bad-request",  "errors": [],  "message": "query parameter 'q' is required"}
{  "ok": false,  "code": "not-authenticate",  "errors": [],  "message": "Authorization not found"}
{  "ok": false,  "code": "forbidden",  "errors": [],  "message": "not allowed for access this resource"}

Riwayat Pergerakan Plat

GET
/api/events/plate-related

Authorization

bearerAuth
AuthorizationBearer <token>

In: header

Query Parameters

plate_number*string

Nomor plat persis seperti hasil pembacaan LPR (huruf kapital, biasanya tanpa spasi). Bila kosong, hasil selalu kosong.

timestamp_from*string

Batas awal rentang waktu (ISO 8601 dengan offset). Wajib: bila kosong query gagal dan respons 500.

Formatdate-time
timestamp_to*string

Batas akhir rentang waktu (ISO 8601 dengan offset). Wajib: bila kosong query gagal dan respons 500.

Formatdate-time
limit?integer

Jumlah maksimum event setelah deduplikasi. Default 10 (UI memakai 1000). Harus berupa angka; nilai bukan angka menghasilkan 500.

Default10
timezone?string

Diterima untuk kompatibilitas dengan klien Lenz, tetapi saat ini tidak diterapkan: timestamp selalu dikembalikan dalam UTC.

disable_base64_image?boolean

Jika true, primary_image/secondary_image (Base64) dihilangkan dan diganti primary_image_url/secondary_image_url. Default false; UI Lenz selalu mengirim true.

Defaultfalse

Response Body

application/json

application/json

application/json

application/json

curl -X GET "https://lenz.example.com/api/events/plate-related?plate_number=B1234XYZ&timestamp_from=2026-09-08T00%3A00%3A00%2B07%3A00&timestamp_to=2026-09-15T23%3A59%3A59%2B07%3A00&limit=1000&timezone=Asia%2FJakarta&disable_base64_image=true"
{  "ok": true,  "message": "successfully get data plate related event",  "data": [    {      "id": 2001,      "analytic_id": "NFV4-LPR2",      "node_num": 2,      "stream_id": "stream-camera-gerbang",      "stream_latitude": -6.2088,      "stream_longitude": 106.8456,      "primary_image_url": "/api/event/image?event_id=7f3c1a2e-4b8d-4e1f-9a6b-2c5d8e9f0a11&type=primary",      "secondary_image_url": "/api/event/image?event_id=7f3c1a2e-4b8d-4e1f-9a6b-2c5d8e9f0a11&type=secondary",      "label": "",      "result": "B1234XYZ",      "location": "Gerbang Utama",      "status": "",      "logic": "LPR",      "timestamp": "2026-09-15T02:10:05Z",      "pipeline_event_id": "7f3c1a2e-4b8d-4e1f-9a6b-2c5d8e9f0a11",      "pipeline_data": {        "event_id": "7f3c1a2e-4b8d-4e1f-9a6b-2c5d8e9f0a11",        "plate_number": "B1234XYZ",        "attributes": {          "character": {            "label": "B1234XYZ",            "confidence": 0.97          },          "vehicle": {            "label": "car",            "confidence": 0.91          }        }      }    }  ]}
{  "ok": false,  "code": "not-authenticate",  "errors": [],  "message": "Authorization not found"}
{  "ok": false,  "code": "forbidden",  "errors": [],  "message": "not allowed for access this resource"}
{  "ok": false,  "code": "internal-server-error",  "errors": [],  "message": "strconv.Atoi: parsing \"abc\": invalid syntax"}

Gambar Deteksi

Saat disable_base64_image=true, kedua endpoint riwayat mengembalikan primary_image_url dan secondary_image_url berupa path relatif /api/event/image?event_id=<pipeline_event_id>&type=primary|secondary. Gabungkan path tersebut dengan basis URL Lenz untuk mengunduh gambarnya; endpoint gambar tidak memerlukan header otentikasi (hanya dicatat di audit log). Nilai event_id yang dipakai adalah pipeline_event_id pada event, bukan id numerik. Field yang sama juga tersedia pada hasil pencarian plat teragregasi (event_id deteksi terbaru) untuk menampilkan thumbnail per plat.

Mengambil potongan wajah sebuah event
curl -X GET "${API_URL}/api/event/image?event_id=c0ffee12-3456-4789-abcd-ef0123456789&type=secondary" \
  --output wajah.jpg

Deduplikasi dan Urutan Hasil

Kedua endpoint riwayat merapikan hasil sebelum mengembalikannya, sehingga jumlah event yang diterima lebih kecil daripada jumlah event mentah di halaman Events:

  • Service mengambil limit × 10 event terbaru dari database, mempertahankan satu event per stream per menit (yang terbaru), mengurutkan dari yang terbaru, lalu memotong ke limit.
  • Khusus plat, database membatasi paling banyak 10 event per jendela 10 menit sebelum tahap di atas.
  • Hasil selalu diurutkan dari terbaru ke terlama; UI Lenz mengurutkan ulang secara kronologis saat membangun timeline.

Karena limit diterapkan setelah deduplikasi, kirim nilai yang cukup besar (UI Lenz memakai 1000) bila Anda membutuhkan seluruh riwayat dalam rentang waktu tersebut.

Riwayat 7 hari sebuah wajah, tanpa Base64 dan embedding
curl -X GET "${API_URL}/api/events/face-related?face_id=abc123def456&timestamp_from=2026-09-09T00:00:00%2B07:00&timestamp_to=2026-09-15T23:59:59%2B07:00&limit=1000&disable_base64_image=true&include_embeddings=false" \
  -H "X-Api-Key: <api-key>"
Riwayat 7 hari sebuah plat, tanpa Base64
curl -X GET "${API_URL}/api/events/plate-related?plate_number=B1234XYZ&timestamp_from=2026-09-09T00:00:00%2B07:00&timestamp_to=2026-09-15T23:59:59%2B07:00&limit=1000&disable_base64_image=true" \
  -H "X-Api-Key: <api-key>"

Parameter timezone pada kedua endpoint riwayat diterima tetapi saat ini tidak diterapkan: timestamp selalu dikembalikan dalam UTC. Konversikan ke zona waktu lokal di sisi klien. Pada search/plates, timezone berfungsi dan memengaruhi first_seen serta last_seen.

Tracking

Telusuri riwayat pergerakan satu wajah atau satu plat nomor lintas kamera dari Face Search dan Plate Search, lengkap dengan timeline kunjungan, rute di peta dan denah, thumbnail deteksi, serta playback rekaman.

Statistics

Susun dashboard statistik dinamis dari data analitik Visionaire, baca hasilnya per periode, stream, dan atribut, lalu bagikan sebagai PDF atau tampilkan di halaman stream.

On this page

Pelacakan WajahRiwayat Pergerakan WajahPelacakan PlatPencarian Plat TeragregasiRiwayat Pergerakan PlatGambar DeteksiDeduplikasi dan Urutan Hasil