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
Copy to clipboard

Parameters

The query parameters for the GET request:

PARAMETER	TYPE	IMPORTANCE	DESCRIPTION
`viewer_identifier`	string	OPTIONAL	Filter for viewer identifiers containing this string
`list_unfinished_segments`	boolean	OPTIONAL	Flag for including unfinished segments in the result (value is true by default)
`date_time_from`	string	OPTIONAL	Start date and time for a period in ISO8601 format
`date_time_to`	string	OPTIONAL	End date and time for a period in ISO8601 format
`_page`	integer	OPTIONAL	Requested page number (value is 1 by default)
`_limit`	integer	OPTIONAL	Requested 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:

KEY	TYPE	DESCRIPTION
`last_activity`	string	Last activity recorded from the viewer
`segments`	array	An array of the viewers segments, which are matching the query parameters
`videos_watched`	integer	Number of distinct medias from the segments array
`viewer_identifier`	string	Viewer identifier string. It can be an e-mail or any string representing a viewer

The segments array contains the following key-value structure:

KEY	TYPE	DESCRIPTION
`id`	string	Uniuque segment id
`content_type`	string	Watched content type
`content_id`	integer
`started_at`	string	Start date and time in ISO8601 format
`finished_at`	string	Finish date and time in ISO8601 format
`from`	integer	Start position of the view for videos in seconds
`to`	integer	End position of the view for videos in seconds
`view_session_id`	string	Player session identifier. Every playing session has a different identifier.
`client_id`	integer	Device identifier
`device_info`	object	Device information parsed from the viewer’s user agent.
`country`	string	The country of the playback
`city`	string	The city of the playback
`is_mobile_view`	boolean	If the playback happened on a mobile device the value is true
`view_type`	string	`onsite` or `offsite`

Example of a success response:

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

Error responses

Possible error responses:

HTTP RESPONSE CODE	ERROR CONDITIONS
400 Bad Request	Validation of the parameters has failed, the response contains a detailed explanation
401 Unauthorized	The provided access token is missing, revoked, expired or malformed
404 Not Found	Resource was not found
503 Service Unavailable	There 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}
Copy to clipboard

Parameters

The query parameters for the GET request:

PARAMETER	TYPE	IMPORTANCE	DESCRIPTION
`content_type`	string	REQUIRED	Type of the content, either `live` or `recorded`
`content_id`	integer	OPTIONAL	A list of comma separated IDs
`viewer_identifier`	string	OPTIONAL	Filter for viewer identifiers containing this string
`list_unfinished_segments`	boolean	OPTIONAL	Flag for including unfinished segments in the result (value is true by default)
`date_time_from`	string	OPTIONAL	Start date and time for a period in ISO8601 format
`date_time_to`	string	OPTIONAL	End date and time for a period in ISO8601 format
`_page`	integer	OPTIONAL	Requested page number (value is 1 by default)
`_limit`	integer	OPTIONAL	Requested 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:

KEY	TYPE	DESCRIPTION
`last_activity`	string	Last activity recorded from the viewer
`segments`	array	An array of the viewers segments, which are matching the query parameters
`videos_watched`	integer	Number of distinct medias from the segments array
`viewer_identifier`	string	Viewer identifier string. It can be an e-mail or any string representing a viewer

The segments array contains the following key-value structure:

KEY	TYPE	DESCRIPTION
`id`	string	Uniuque segment id
`content_type`	string	Watched content type
`content_id`	integer
`started_at`	string	Start date and time in ISO8601 format
`finished_at`	string	Finish date and time in ISO8601 format
`from`	integer	Start position of the view for videos in seconds
`to`	integer	End position of the view for videos in seconds
`view_session_id`	string	Player session identifier. Every playing session has a different identifier.
`client_id`	integer	Device identifier
`device_info`	object	Device information parsed from the viewer’s user agent.
`country`	string	The country of the playback
`city`	string	The city of the playback
`is_mobile_view`	boolean	If the playback happened on a mobile device the value is true
`view_type`	string	`onsite` or `offsite`

Example of a success response:

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

Error responses

Possible error responses:

HTTP RESPONSE CODE	ERROR CONDITIONS
400 Bad Request	Validation of the parameters has failed, the response contains a detailed explanation
401 Unauthorized	The provided access token is missing, revoked, expired or malformed
404 Not Found	Resource was not found
503 Service Unavailable	There is a temporary error on the server which makes it impossible to serve the request

Edit this page on GitHub

Getting started

Using the Analytics API: Views

Viewers

List of the unique viewers for all contents

Parameters

Success response

Error responses

List of the unique viewers for a specific content type

Parameters

Success response

Error responses