Visitor Journey Tracking

This endpoint returns zone-by-zone journey events for individual visits, including dwell time and zone transitions (entered from / exited to).

Visit

A visit represents a single in-store presence for a device. A visit can include multiple zone events (e.g., Entrance → Produce → Dairy → Checkout).

Session

A session aligns to a visit per device.

• A session begins when your Digital Asset (or Wi-Fi logs) is observed in-store and records activity.
• A session ends when activity stops, and no further activity is observed.
• Multiple interruptions/reopens within a 60-minute window are consolidated and billed as a single session.

Zone event

A zone event is a segment of the journey where the visitor is observed within a single zone, with:

• entry context (zone_entered_from)
• exit context (zone_exited_to)
• dwell time (dwell_time_seconds)

Resource [GET]

/bi/visit-journey-events/

This resource supports pagination. Due to increased data volume, pagination allows fetching results in batches (pages) for a specified time interval.

---

URL Parameters

• store_code — Optional
  Filter results to a single store.
• datetime_gte — Required
  Start datetime (UTC) inclusive. Format: ISO 8601.
• datetime_lte — Required
  End datetime (UTC) inclusive. Format: ISO 8601.
• page_size — Optional
  Number of results per page.
  Default: 1000, Max: 10000
• page — Optional
  Page number (used when paginating).

Note: For large intervals, prefer daily windows (e.g., 24h) and paginate.

---

Response

The response is paginated:

• count is the total number of results across the query.
• next and previous are URLs to fetch the adjacent pages.
• results is an array of zone events.

Each object in results contains:

• session_id — String
  Session identifier (aligned to “visit per device”, stitched within 60 minutes).
• visit_id — String
  Visit identifier (store visit per device).
• user_id — String | null
  User identifier (if available, e.g., logged-in app user). May be null.
• device_id — String
  Pseudonymous device identifier (privacy-safe token).
• store_name — String
  Store name.
• store_code — String
  Store code.
• zone_name — String
  Human-readable zone name.
• zone_serial_code — String
  Internal zone code used for stable referencing across systems.
• zone_entered_from — String | null
  Previous zone label. null if first event in the visit.
• zone_exited_to — String | null
  Next zone label. null if last event in the visit.
• dwell_time_seconds — Integer
  Time spent in the zone (seconds).
• event_start — String
  Zone event start timestamp (ISO 8601 UTC).
• event_end — String
  Zone event end timestamp (ISO 8601 UTC).
• source — String
  Source of observation, e.g. app_ble, wifi, camera_fused.

---

Example response

{
  "count": 6,
  "next": null,
  "previous": null,
  "results": [
    {
      "session_id": "ses_2c7e41b9f0d84c7a",
      "visit_id": "vst_8f2c9a1d3b7a4c1e",
      "user_id": "usr_4a91d2c8",
      "device_id": "dev_9b3f1c2a7e",
      "date_of_visit": "2025-08-12",
      "store_name": "SuperMart Downtown",
      "store_code": "SM-001",
      "zone_name": "Entrance & Promotions",
      "zone_serial_code": "L0-ENT-PRO-001",
      "zone_entered_from": "Outside",
      "zone_exited_to": "Fresh Produce",
      "dwell_time_seconds": 190,
      "event_start": "2025-08-12T13:00:00Z",
      "event_end": "2025-08-12T13:03:10Z",
      "source": "app_sdk"
    },
    {
      "session_id": "ses_2c7e41b9f0d84c7a",
      "visit_id": "vst_8f2c9a1d3b7a4c1e",
      "user_id": "usr_4a91d2c8",
      "device_id": "dev_9b3f1c2a7e",
      "date_of_visit": "2025-08-12",
      "store_name": "SuperMart Downtown",
      "store_code": "SM-001",
      "zone_name": "Fresh Produce",
      "zone_serial_code": "L0-PRD-FRU-014",
      "zone_entered_from": "Entrance & Promotions",
      "zone_exited_to": "Bakery",
      "dwell_time_seconds": 540,
      "event_start": "2025-08-12T13:03:10Z",
      "event_end": "2025-08-12T13:12:10Z",
      "source": "app_sdk"
    },
    {
      "session_id": "ses_2c7e41b9f0d84c7a",
      "visit_id": "vst_8f2c9a1d3b7a4c1e",
      "user_id": "usr_4a91d2c8",
      "device_id": "dev_9b3f1c2a7e",
      "date_of_visit": "2025-08-12",
      "store_name": "SuperMart Downtown",
      "store_code": "SM-001",
      "zone_name": "Bakery",
      "zone_serial_code": "L0-BKY-BRD-006",
      "zone_entered_from": "Fresh Produce",
      "zone_exited_to": "Dairy",
      "dwell_time_seconds": 310,
      "event_start": "2025-08-12T13:12:10Z",
      "event_end": "2025-08-12T13:17:20Z",
      "source": "app_sdk"
    },
    {
      "session_id": "ses_2c7e41b9f0d84c7a",
      "visit_id": "vst_8f2c9a1d3b7a4c1e",
      "user_id": "usr_4a91d2c8",
      "device_id": "dev_9b3f1c2a7e",
      "date_of_visit": "2025-08-12",
      "store_name": "SuperMart Downtown",
      "store_code": "SM-001",
      "zone_name": "Dairy",
      "zone_serial_code": "L0-DRY-MLK-022",
      "zone_entered_from": "Bakery",
      "zone_exited_to": "Household & Cleaning",
      "dwell_time_seconds": 460,
      "event_start": "2025-08-12T13:17:20Z",
      "event_end": "2025-08-12T13:25:00Z",
      "source": "app_sdk"
    },
    {
      "session_id": "ses_2c7e41b9f0d84c7a",
      "visit_id": "vst_8f2c9a1d3b7a4c1e",
      "user_id": "usr_4a91d2c8",
      "device_id": "dev_9b3f1c2a7e",
      "date_of_visit": "2025-08-12",
      "store_name": "SuperMart Downtown",
      "store_code": "SM-001",
      "zone_name": "Household & Cleaning",
      "zone_serial_code": "L0-HOU-CLN-031",
      "zone_entered_from": "Dairy",
      "zone_exited_to": "Checkout Queue",
      "dwell_time_seconds": 380,
      "event_start": "2025-08-12T13:25:00Z",
      "event_end": "2025-08-12T13:31:20Z",
      "source": "app_sdk"
    },
    {
      "session_id": "ses_2c7e41b9f0d84c7a",
      "visit_id": "vst_8f2c9a1d3b7a4c1e",
      "user_id": "usr_4a91d2c8",
      "device_id": "dev_9b3f1c2a7e",
      "date_of_visit": "2025-08-12",
      "store_name": "SuperMart Downtown",
      "store_code": "SM-001",
      "zone_name": "Checkout Queue",
      "zone_serial_code": "L0-CHK-QUE-001",
      "zone_entered_from": "Household & Cleaning",
      "zone_exited_to": "Cashlines",
      "dwell_time_seconds": 260,
      "event_start": "2025-08-12T13:31:20Z",
      "event_end": "2025-08-12T13:35:40Z",
      "source": "app_sdk"
    }
  ]
}

Notes and common questions

Does one visit always equal one session?
For billing and analytics, we treat a session as a visit per device, with 60-minute stitching to avoid multiple app opens during a single visit being counted multiple times.

**Can **user_idbe missing?
Yes. If the visitor is not logged in, or if the integration uses privacy-safe pseudonymous identifiers only, user_id may be null.

**What does **sourcemean?
It indicates the signal that produced the event (e.g., Wi-Fi telemetry, app BLE, camera-derived, or fused).