Skip to main contentIBM Video Streaming Developers

Viewers

List of the unique viewers for all contents

You can get a list of every individual viewer for all of your channels by calling this endpoint. You look for a specific viewer by using the viewer_identifier parameter for matching an identifier or part of an identifier.

GET https://analytics-api.video.ibm.com/v1/viewers

Parameters

The query parameters for the GET request:

PARAMETERTYPEIMPORTANCE DESCRIPTION
viewer_identifierstringOPTIONALFilter for viewer identifiers containing this string
list_unfinished_segmentsbooleanOPTIONALFlag for including unfinished segments in the result (value is true by default)
date_time_fromstringOPTIONALStart date and time for a period in ISO8601 format
date_time_tostringOPTIONALEnd date and time for a period in ISO8601 format
_pageintegerOPTIONALRequested page number (value is 1 by default)
_limitintegerOPTIONALRequested page size (value is 10 by default, max. 10 000)

Success response

Upon success a response with HTTP status “200 OK” is returned with an array under a data key. The elements of the array contain every viewer matching the query parameters. Each viewer has the following attributes under the attributes key:

KEYTYPEDESCRIPTION
last_activitystringLast activity recorded from the viewer
segmentsarrayAn array of the viewers segments, which are matching the query parameters
videos_watchedintegerNumber of distinct medias from the segments array
viewer_identifierstringViewer identifier string. It can be an e-mail or any string representing a viewer

The segments array contains the following key-value structure:

KEYTYPEDESCRIPTION
idstringUniuque segment id
content_typestringWatched content type
content_idinteger
started_atstringStart date and time in ISO8601 format
finished_atstringFinish date and time in ISO8601 format
fromintegerStart position of the view for videos in seconds
tointegerEnd position of the view for videos in seconds
view_session_idstringPlayer session identifier. Every playing session has a different identifier.
client_idintegerDevice identifier
device_infoobjectDevice information parsed from the viewer’s user agent.
countrystringThe country of the playback
citystringThe city of the playback
is_mobile_viewbooleanIf the playback happened on a mobile device the value is true
view_typestringonsite or offsite

Example of a success response:

{
"data": [
{
"attributes": {
"last_activity": "2018-07-16T19:20:30+01:00",
"segments": [
{
"city": "Budapest",
"client_id": "8776986273576598258658",

Error responses

Possible error responses:

HTTP RESPONSE CODEERROR CONDITIONS
400 Bad RequestValidation of the parameters has failed, the response contains a detailed explanation
401 UnauthorizedThe provided access token is missing, revoked, expired or malformed
404 Not FoundResource was not found
503 Service UnavailableThere is a temporary error on the server which makes it impossible to serve the request

List of the unique viewers for a specific content type

You can get a list of every individual viewer for just a specific content type, such as live or on demand content, by calling this endpoint. You can also look for a specific viewer by using the viewer_identifier parameter for matching an identifier or part of an identifier.

GET https://analytics-api.video.ibm.com/v1/viewers/{content_type}

Parameters

The query parameters for the GET request:

PARAMETERTYPEIMPORTANCE DESCRIPTION
content_typestringREQUIREDType of the content, either live or recorded
content_idintegerOPTIONALA list of comma separated IDs
viewer_identifierstringOPTIONALFilter for viewer identifiers containing this string
list_unfinished_segmentsbooleanOPTIONALFlag for including unfinished segments in the result (value is true by default)
date_time_fromstringOPTIONALStart date and time for a period in ISO8601 format
date_time_tostringOPTIONALEnd date and time for a period in ISO8601 format
_pageintegerOPTIONALRequested page number (value is 1 by default)
_limitintegerOPTIONALRequested page size (value is 10 by default, max. 10 000)

Success response

Upon success a response with HTTP status “200 OK” is returned with an array under a data key. The elements of the array contain every viewer matching the query parameters. Each viewer viewer has the following attributes under the attributes key:

KEYTYPEDESCRIPTION
last_activitystringLast activity recorded from the viewer
segmentsarrayAn array of the viewers segments, which are matching the query parameters
videos_watchedintegerNumber of distinct medias from the segments array
viewer_identifierstringViewer identifier string. It can be an e-mail or any string representing a viewer

The segments array contains the following key-value structure:

KEYTYPEDESCRIPTION
idstringUniuque segment id
content_typestringWatched content type
content_idinteger
started_atstringStart date and time in ISO8601 format
finished_atstringFinish date and time in ISO8601 format
fromintegerStart position of the view for videos in seconds
tointegerEnd position of the view for videos in seconds
view_session_idstringPlayer session identifier. Every playing session has a different identifier.
client_idintegerDevice identifier
device_infoobjectDevice information parsed from the viewer’s user agent.
countrystringThe country of the playback
citystringThe city of the playback
is_mobile_viewbooleanIf the playback happened on a mobile device the value is true
view_typestringonsite or offsite

Example of a success response:

{
"data": [
{
"attributes": {
"last_activity": "2020-07-16T19:20:30+01:00",
"segments": [
{
"city": "Budapest",
"client_id": "8776986273576598258658",

Error responses

Possible error responses:

HTTP RESPONSE CODEERROR CONDITIONS
400 Bad RequestValidation of the parameters has failed, the response contains a detailed explanation
401 UnauthorizedThe provided access token is missing, revoked, expired or malformed
404 Not FoundResource was not found
503 Service UnavailableThere is a temporary error on the server which makes it impossible to serve the request