Skip to main contentIBM Video Streaming Developers

Views

Raw view export for a given time period

This endpoint lists view segments in the requested time period. Segments are generated by events from the users, like play, pause, seek.

The date_time_from and date_time_to parameters control how the Analytics API filters the response. By default, the API returns all segments which meet at least one of the following criteria:

  • the view started before the date range and ended in the defined range
  • the view started and finished inside the defined range or not finished yet
  • the view started in the defined range and finished after the defined range or not finished yet

You can control this behavior with two flags: list_unfinished_segments and inclusive_range. Both parameters are set to true by default. When you set the list_unfinished_segments to false, the API will return only the finished segments. However, when you set the inclusive_range parameter to false, only those segments will be returned whose started and finished times are in the defined range.

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

Parameters

The query parameters for the GET request:

PARAMETERTYPEIMPORTANCE DESCRIPTION
date_time_fromstringREQUIREDStart date and time for a period in ISO8601 format
date_time_tostringREQUIREDEnd date and time for a period in ISO8601 format
list_unfinished_segmentsbooleanOPTIONALFlag for including unfinished segments in the result (value is true by default)
inclusive_rangebooleanOPTIONALThis flag controls the behavior of the date and time range filter (value is true by default)
_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 view matching the query parameters. Each view has the following attributes under the attributes key:

KEYTYPEDESCRIPTION
view_idstringUnique segment ID
content_typeobjectWatched 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
tointegerEnd position of the view for videos
view_session_idobjectPlayer 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
viewer_identifierstringViewer identifier string. It can be an e-mail or any string representing a viewer

Example of a success response:

{
"data": [
{
"attributes": {
"city": "Budapest",
"client_id": "13602851710424434669",
"content_id": "112342345",
"content_type": "live",
"country": "HU",

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

Raw view export of a specific content type for a given time period

This endpoint lists view segments in the requested time period for a specific content type, such as live on on-demand. Segments are generated by events from the users, like play, pause, seek.

GET https://analytics-api.video.ibm.com/v1/views/{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
date_time_fromstringREQUIREDStart date and time for a period in ISO8601 format
date_time_tostringREQUIREDEnd date and time for a period in ISO8601 format
list_unfinished_segmentsbooleanOPTIONALFlag for including unfinished segments in the result (value is true by default)
inclusive_rangebooleanOPTIONALThis flag controls the behavior of the date and time range filter (value is true by default)
_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 view matching the query parameters. Each view has the following attributes under the attributes key:

KEYTYPEDESCRIPTION
view_idstringUnique segment ID
content_typeobjectWatched 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
tointegerEnd position of the view for videos
view_session_idobjectPlayer 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
viewer_identifierstringViewer identifier string. It can be an e-mail or any string representing a viewer

Example of a success response:

{
"data": [
{
"attributes": {
"city": "Budapest",
"client_id": "13602851710424434669",
"content_id": "112342345",
"content_type": "live",
"country": "HU",

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

Raw view export on all videos by channel ID

This endpoint lists view segments for all recorded videos attached to a specific channel. Segments are generated by events from the users, like play, pause, seek.

GET https://analytics-api.video.ibm.com/v1/views/recorded/channel

Parameters

The query parameters for the GET request:

PARAMETERTYPEIMPORTANCE DESCRIPTION
channel_idintegerREQUIREDA list of comma separated IDs
date_time_fromstringREQUIREDStart date and time for a period in ISO8601 format
date_time_tostringREQUIREDEnd date and time for a period in ISO8601 format
list_unfinished_segmentsbooleanOPTIONALFlag for including unfinished segments in the result (value is true by default)
inclusive_rangebooleanOPTIONALThis flag controls the behavior of the date and time range filter (value is true by default)
_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 view matching the query parameters. Each view has the following attributes under the attributes key:

KEYTYPEDESCRIPTION
view_idstringUnique segment ID
content_typeobjectWatched 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
tointegerEnd position of the view for videos
view_session_idobjectPlayer 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
viewer_identifierstringViewer identifier string. It can be an e-mail or any string representing a viewer

Example of a success response:

{
"data": [
{
"attributes": {
"city": "Budapest",
"client_id": "13602851710424434669",
"content_id": "112342345",
"content_type": "live",
"country": "HU",

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