Stream Viewer Geolocations

Returns geographic locations of viewers watching a specific stream, with optional marker clustering.

Request

Property	Value
Method	`GET`
URL	`/api/streams/{appName}/{streamKey}/viewers/geolocation`
Content-Type	`application/json`
Authentication	Bearer Token

Request

bash

curl -X GET "{BASE_URL}/api/streams/{appName}/{streamKey}/viewers/geolocation" \
  -H "Authorization: Bearer YOUR_TOKEN"

Path Parameters

Parameter	Type	Required	Description
`appName`	string	Yes	Application name
`streamKey`	string	Yes	Stream key

Request

bash

curl -X GET "{BASE_URL}/api/streams/{appName}/{streamKey}/viewers/geolocation" \
  -H "Authorization: Bearer YOUR_TOKEN"

Query Parameters

Parameter	Type	Required	Default	Description
`aggregation`	"none" \| "auto" \| "cluster"	No	-	Marker aggregation mode

With query parameters

bash

curl -X GET "{BASE_URL}/api/streams/{appName}/{streamKey}/viewers/geolocation?aggregation=value" \
  -H "Authorization: Bearer YOUR_TOKEN"

Response Body

Developer Info

Parameter	Type	Description
`data.dev`	object	Development/debug information
`data.dev.aggregationMode`	string	Applied aggregation mode (`"NONE"`, `"AUTO"`, or `"CLUSTER"`)

Statistics

Parameter	Type	Description
`data.stats`	object	Summary statistics for the map
`data.stats.isClustered`	boolean	Indicates if markers are clustered
`data.stats.totalMarkers`	integer	Total number of markers on the map

Markers

Parameter	Type	Description
`data.markers`	array	Array of map markers
`data.markers[].type`	string	Marker type
`data.markers[].position`	number[]	Geographic coordinates as `[latitude, longitude]`
`data.markers[].data`	object	Viewer data associated with this marker
`data.markers[].data.connectionId`	string	Unique identifier of the viewer session
`data.markers[].data.streamKey`	string	Stream key being viewed
`data.markers[].data.outBandwidth`	integer	Outgoing bandwidth in bytes per second
`data.markers[].data.healthScore`	integer	Connection health score (0-100)

Timestamp

Parameter	Type	Description
`data.timestamp`	integer	Data timestamp (Unix timestamp in ms)

Metadata

Parameter	Type	Description
`meta.executionTime`	integer	Request processing time in milliseconds
`meta.generatedAt`	integer	Response generation timestamp (Unix timestamp in ms)

Successful Response (200)

json

{
  "data": {
    "dev": {
      "aggregationMode": "AUTO"
    },
    "stats": {
      "isClustered": false,
      "totalMarkers": 1
    },
    "markers": [
      {
        "type": "individual",
        "position": [53.0176, 18.6202],
        "data": {
          "connectionId": "v_nkro1il5mipys3xm",
          "streamKey": "f1",
          "outBandwidth": 231460,
          "healthScore": 0
        }
      }
    ],
    "timestamp": 1764763772219
  },
  "meta": {
    "executionTime": 2,
    "generatedAt": 1764763772220
  }
}

Error Response (4xx/5xx)

Parameter	Type	Description
`message`	string	Human-readable error message

json

{
  "message": "Error message"
}

Support Needed?

Create a free ticket and our support team will provide you necessary assistance.