IPera Starling | Developer Hub

# Location Analytics

# Get Active Sessions

Get real-time location presence data for all currently active sessions. This endpoint returns information about guests currently present at locations, including their latest position coordinates from the location tracking system.

This endpoint returns all active sessions without pagination for real-time monitoring dashboards.

# Endpoint

GET /locations-analytics/active-sessions

# Parameters

Name Type Description
location_id string Filter by location/venue ID
building_id string Filter by building ID
floor_id string Filter by floor ID
zone_id string Filter by zone ID
segment_id string Filter by guest segment/tag ID
data_type integer Filter by data type (1=WiFi, 2=BLE)
connected integer Filter by connection status. Use 1 to retrieve only currently connected users.0 for disconnected users

# Response

TIP

HTTP/1.1 200 OK

{
  "data": [
    {
      "mac_address": "AA:BB:CC:DD:EE:FF",
      "data_type": 1,
      "x": 123.45,
      "y": 678.90,
      "location_id": "x1Y2z3A4b5C",
      "location": "Main Campus",
      "building_id": "a2B3c4D5e6F",
      "building": "Building A",
      "floor_id": "f7G8h9I0j1K",
      "floor": "Floor 1",
      "zone_id": "z2L3m4N5o6P",
      "zone": "Lobby",
      "gender": "Male",
      "nationality": "US",
      "country_of_residency": "CA",
      "guest_id": "g8Q9r0S1t2U",
      "segment": [
        {
          "id": "s3V4w5X6y7Z",
          "name": "VIP"
        }
      ],
      "last_seen": "2025-10-17T10:30:00.000000Z",
      "connected": 1
    },
    {
      "mac_address": "11:22:33:44:55:66",
      "data_type": 2,
      "x": null,
      "y": null,
      "location_id": "x1Y2z3A4b5C",
      "location": "Main Campus",
      "building_id": null,
      "building": null,
      "floor_id": null,
      "floor": null,
      "zone_id": null,
      "zone": null,
      "gender": null,
      "nationality": null,
      "country_of_residency": null,
      "guest_id": null,
      "segment": [],
      "last_seen": "2025-10-17T10:25:00.000000Z",
      "connected": 0
    }
  ]
}

# Response Fields

Field Type Description
mac_address string Device MAC address
data_type integer Data source type (1=WiFi, 2=BLE)
x float|null X coordinate from latest location log
y float|null Y coordinate from latest location log
location_id string|null Location/venue hashed ID
location string|null Location/venue name
building_id string|null Building hashed ID
building string|null Building name
floor_id string|null Floor hashed ID
floor string|null Floor name
zone_id string|null Zone hashed ID
zone string|null Zone name
gender string|null Guest gender ("Male", "Female", or "Unknown")
nationality string|null Guest nationality country code
country_of_residency string|null Guest residency country code
guest_id string|null Guest hashed ID
segment array Guest segments/tags (array of {id, name} objects)
last_seen datetime|null Last activity timestamp
connected integer Connection status (0=Disconnected, 1=Connected).
Note: 0 is expected when a guest is detected in the area (Active Session) but is not connected to WiFi.

# Get Location Sessions

# --> (Deprecated)

By using this API endpoint, it is possible to get the list of location sessions.

Please note that you cannot get more than 100 records per request. In case you need to get more than 100 records, then you should make more than one request.

# Endpoint

GET /locations-analytics/sessions

# Parameters

Name Type Description
guest_id string Guest ID
location_id string Location / Venue ID
mac string Guest device MAC address
started_at date Returns entries started after the entered starting date (format: yyyy-mm-dd hh:ii)
ended_at date Returns entries ended before the entered ending date (format: yyyy-mm-dd hh:ii)
visit_type int Visit type
per_page integer The number of records returned. Default is 10, maximum is 100

# Response

TIP

HTTP/1.1 200 OK

{
  "data": [
    {
      "id": "pR3zOKmvzqe",
      "guest_id": "VGBzq2o1XQ5",
      "location_id": "1kgXJ6RXN9D",
      "mac": "74:e5:0b:10:c2:cc",
      "started_at": "2017-10-24T13:11:25.000000Z",
      "ended_at": "2017-10-24T18:11:25.000000Z",
      "duration": "600",
      "visit_type": 1
    }
  ],

  "links": {
    "first": "[[BaseUrl]]/locations-analytics/sessions?page=1",
    "last": null,
    "prev": null,
    "next": "[[BaseUrl]]/locations-analytics/sessions?page=2"
  },

  "meta": {
    "current_page": 1,
    "from": 1,
    "path": "[[BaseUrl]]/locations-analytics/sessions",
    "per_page": 10,
    "to": 10
  }
}

# Get Location Sessions Count

# --> (Deprecated)

By using this API endpoint, it is possible to get the count of location sessions.

# Endpoint

GET /locations-analytics/sessions/count

# Parameters

Name Type Description
guest_id string Guest ID
location_id string Location / Venue ID
mac string Guest device MAC address
started_at date Returns entries started after the entered starting date (format: yyyy-mm-dd hh:ii)
ended_at date Returns entries ended before the entered ending date (format: yyyy-mm-dd hh:ii)
visit_type int Visit type
per_page integer The number of records returned. Default is 10, maximum is 100

# Response

TIP

HTTP/1.1 200 OK

{
  "count": 1000
}

# Get Location Session Details

Get location session details.

# Endpoint

GET /locations-analytics/sessions/:id

# Parameters

Name Type Description
id string location ID

# Response

TIP

HTTP/1.1 200 OK

{
  "data": {
      "id": "pR3zOKmvzqe",
      "guest_id": "VGBzq2o1XQ5",
      "location_id": "1kgXJ6RXN9D",
      "mac": "74:e5:0b:10:c2:cc",
      "started_at": "2017-10-24T13:11:25.000000Z",
      "ended_at": "2017-10-24T18:11:25.000000Z",
      "duration": "600",
      "visit_type": 1
  }
}

DANGER

HTTP/1.1 404 Not Found

{
  "error": "Record not found"
}

# Get Location Logs

# --> (Deprecated)

By using this API endpoint, it is possible to get the list of location logs.

Please note that you cannot get more than 100 records per request. In case you need to get more than 100 records, then you should make more than one request.

# Endpoint

GET /locations-analytics/location-logs

# Parameters

Name Type Description
guest_id string Guest ID
guest_mac string Guest MAC address
session_id string Session ID of the log
zone_id string Zone ID
timestamp date Returns entries created after the entered timestamp (format: yyyy-mm-dd hh:ii)
per_page integer The number of records returned. Default is 10, maximum is 100

# Response

TIP

HTTP/1.1 200 OK

{
  "data": [
    {
      "guest_id": "VGBzq2o1XQ5",
      "guest_mac": "74:e5:0b:10:c2:cc",
      "session_id": "Zk5reDj6baK",
      "zone_id": "pR3zOKmvzqe",
      "timestamp": "2017-10-24T13:11:25.000000Z",
      "duration": "600"
    },
    {
      "guest_id": "DEFzq2o1XQ5",
      "guest_mac": "82:g6:0b:10:c2:dd",
      "session_id": "9apvYXJr5l0",
      "zone_id": "p79zOKmecq1",
      "timestamp": "2017-10-24T13:11:25.000000Z",
      "duration": "400"
    }
  ],

  "links": {
    "first": "[[BaseUrl]]/locations-analytics/location-logs?page=1",
    "last": null,
    "prev": null,
    "next": "[[BaseUrl]]/locations-analytics/location-logs?page=2"
  },

  "meta": {
    "current_page": 1,
    "from": 1,
    "path": "[[BaseUrl]]/locations-analytics/location-logs",
    "per_page": 10,
    "to": 10
  }
}

# Get Location Logs Count

# --> (Deprecated)

By using this API endpoint, it is possible to get the count of the location logs.

# Endpoint

GET /locations-analytics/location-logs/count

# Parameters

Name Type Description
guest_id string Guest ID
guest_mac string Guest MAC address
session_id string Session ID of the log
zone_id string Zone ID
timestamp date Returns entries created after the entered timestamp (format: yyyy-mm-dd hh:ii)
per_page integer The number of records returned. Default is 10, maximum is 100

# Response

TIP

HTTP/1.1 200 OK

{
  "count": 1000
}
Last Updated: 11/25/2025, 2:12:49 PM

← Tenants →