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:
| PARAMETER | TYPE | IMPORTANCE | DESCRIPTION |
|---|---|---|---|
date_time_from | string | REQUIRED | Start date and time for a period in ISO8601 format |
date_time_to | string | REQUIRED | End date and time for a period in ISO8601 format |
list_unfinished_segments | boolean | OPTIONAL | Flag for including unfinished segments in the result (value is true by default) |
inclusive_range | boolean | OPTIONAL | This flag controls the behavior of the date and time range filter (value is true by default) |
_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 view
matching the query parameters. Each view has the following attributes under the attributes key:
| KEY | TYPE | DESCRIPTION |
|---|---|---|
view_id | string | Unique segment ID |
content_type | object | 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 |
to | integer | End position of the view for videos |
view_session_id | object | 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 |
viewer_identifier | string | Viewer 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 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 |
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:
| 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 |
date_time_from | string | REQUIRED | Start date and time for a period in ISO8601 format |
date_time_to | string | REQUIRED | End date and time for a period in ISO8601 format |
list_unfinished_segments | boolean | OPTIONAL | Flag for including unfinished segments in the result (value is true by default) |
inclusive_range | boolean | OPTIONAL | This flag controls the behavior of the date and time range filter (value is true by default) |
_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 view
matching the query parameters. Each view has the following attributes under the attributes key:
| KEY | TYPE | DESCRIPTION |
|---|---|---|
view_id | string | Unique segment ID |
content_type | object | 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 |
to | integer | End position of the view for videos |
view_session_id | object | 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 |
viewer_identifier | string | Viewer 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 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 |
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:
| PARAMETER | TYPE | IMPORTANCE | DESCRIPTION |
|---|---|---|---|
channel_id | integer | REQUIRED | A list of comma separated IDs |
date_time_from | string | REQUIRED | Start date and time for a period in ISO8601 format |
date_time_to | string | REQUIRED | End date and time for a period in ISO8601 format |
list_unfinished_segments | boolean | OPTIONAL | Flag for including unfinished segments in the result (value is true by default) |
inclusive_range | boolean | OPTIONAL | This flag controls the behavior of the date and time range filter (value is true by default) |
_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 view
matching the query parameters. Each view has the following attributes under the attributes key:
| KEY | TYPE | DESCRIPTION |
|---|---|---|
view_id | string | Unique segment ID |
content_type | object | 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 |
to | integer | End position of the view for videos |
view_session_id | object | 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 |
viewer_identifier | string | Viewer 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 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 |