Analytics API Documentation

Introduction

Base URL

Version: 1.0.3

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

Authentication

The API uses JWT token for authentication. The API accepts the token in the Authorization header, in the following format: Authorization: eyJhbGciOiJIUzI1NiIsInR5cCI6Ik...0RMHrHDcEfxjoYZgeFONFh7HgQ This header must be included with every request.

Obtaining the Access token

You can get JWT token from the OAuth2 token endpoint by setting the token_type parameter to jwt. This parameter must be set as HTTP POST parameter.

The OAuth2 flows are described here: http://developers.video.ibm.com/channel-api/getting-started.html

The recommended authentication flow is Client credentials.

Time format

Every time field provided by the API is formatted by ISO8601 format (eg. 2018-07-16T19:20:30+01:00). The API also accepts parameters in this format only.

Terminology

  • media: Media is a common word for both live broadcasts and videos
  • content type: The API has knowledge of two types of content: live broadcast and videos
  • content id: A numeric identifier of the media. For Live it means channel id, for video it means video id
  • segment: A part of the media watched by the user

Response times

Depending on your query and the underlying data size the response might take a minute.

Content types

Default request content-types: application/json

Default response content-types: application/json

Schemes: https

API Summary

path operation description
/viewers GET List of the unique viewers for all contents
/viewers/{content_type} GET List of the unique viewers for a specific content type
/views GET Raw view export for a given time period.
/views/{content_type} GET Raw view export for a given time period

Security

JWTHeader
Type: apiKey
Name Authorization
In header

List of the unique viewers for all contents

GET /viewers

You can get every individual viewer appeared on all of your channels by calling this endpoint. If you look for a specific viewer you can use the viewer_identifier parameter for matching an identifier or part of an identifier.

Request Parameters

name description type data type required annotation
Authorization JWT token header string yes #/parameters/authParameter
viewer_identifier Filter for viewer identifiers containing this string query string #/parameters/viewerIdSearchStringQueryParameter
list_unfinished_segments Flag for including unfinished segments in the result query boolean,
default value: true
#/parameters/unfinishedParameter
_page Defines the page to get query number,
{ x ∈ ℝ | x ≥ 1 }
default value: 1
#/parameters/offestParameter
_limit Defines how many resources to get query number,
{ x ∈ ℝ | 1 ≤ x ≤ 10000 }
default value: 10
#/parameters/limitParameter

Responses

200 #/responses/ViewerTrackingViewerList

Uses default content-types: application/json

property type value(s)
resources [object] Viewer
pagination object
property type value(s)
count number
self object
property type
href string
first object
property type
href string
prev object
property type
href string
next object
property type
href string
last object
property type
href string

Example for application/json

{
    "pagination": {
        "count": 10,
        "first": {
            "href": "/views?_page=1&_limit=1"
        },
        "last": {
            "href": "/views?_page=10&_limit=1"
        },
        "next": {
            "href": "/views?_page=2&_limit=1"
        },
        "prev": null,
        "self": {
            "href": "/views?_page=1&_limit=1"
        }
    },
    "resources": [
        {
            "attributes": {
                "last_activity": "2018-07-16T19:20:30+01:00",
                "segments": [
                    {
                        "city": "Budapest",
                        "client_id": "8776986273576598258658",
                        "content_id": 77569623,
                        "content_type": "live",
                        "country": "HU",
                        "finished_at": "2018-07-16T19:20:40+01:00",
                        "from": 0,
                        "id": "4bfc69b5-1320-4a44-a8d6-1fe1f397fb94",
                        "is_mobile_view": false,
                        "started_at": "2018-07-16T19:20:30+01:00",
                        "to": 0,
                        "view_session_id": "7f66d911:8b7aa82c",
                        "view_type": "onsite"
                    }
                ],
                "videos_watched": 10,
                "viewer_identifier": "some.viewer@example.com"
            },
            "type": "Viewer"
        }
    ]
}
400 #/responses/BadRequest

Uses default content-types: application/json

property type value(s)
errors [object]
property type value(s)
status number
title string
detail string
source object
property type
pointer string

List of the unique viewers for a specific content type

GET /viewers/{content_type}

Request Parameters

name description type data type required annotation
Authorization JWT token header string yes #/parameters/authParameter
content_type Type of the content eg. Recorded path string,
x ∈ { live , recorded }
yes #/parameters/contentTypeParameter
content_id A list of comma separated IDs query integer #/parameters/contentTypeParameter
viewer_identifier Filter for viewer identifiers containing this string query string #/parameters/viewerIdSearchStringQueryParameter
list_unfinished_segments Flag for including unfinished segments in the result query boolean,
default value: true
#/parameters/unfinishedParameter
_page Defines the page to get query number,
{ x ∈ ℝ | x ≥ 1 }
default value: 1
#/parameters/offestParameter
_limit Defines how many resources to get query number,
{ x ∈ ℝ | 1 ≤ x ≤ 10000 }
default value: 10
#/parameters/limitParameter

Responses

200 #/responses/ViewerTrackingViewerList

Uses default content-types: application/json

property type value(s)
resources [object] Viewer
pagination object
property type value(s)
count number
self object
property type
href string
first object
property type
href string
prev object
property type
href string
next object
property type
href string
last object
property type
href string

Example for application/json

{
"pagination": {
    "count": 10,
    "first": {
        "href": "/views?_page=1&_limit=1"
    },
    "last": {
        "href": "/views?_page=10&_limit=1"
    },
    "next": {
        "href": "/views?_page=2&_limit=1"
    },
    "prev": null,
    "self": {
        "href": "/views?_page=1&_limit=1"
    }
},
"resources": [
    {
        "attributes": {
            "last_activity": "2018-07-16T19:20:30+01:00",
            "segments": [
                {
                    "city": "Budapest",
                    "client_id": "8776986273576598258658",
                    "content_id": 77569623,
                    "content_type": "live",
                    "country": "HU",
                    "finished_at": "2018-07-16T19:20:40+01:00",
                    "from": 0,
                    "id": "4bfc69b5-1320-4a44-a8d6-1fe1f397fb94",
                    "is_mobile_view": false,
                    "started_at": "2018-07-16T19:20:30+01:00",
                    "to": 0,
                    "view_session_id": "7f66d911:8b7aa82c",
                    "view_type": "onsite"
                }
            ],
            "videos_watched": 10,
            "viewer_identifier": "some.viewer@example.com"
        },
        "type": "Viewer"
    }
]
}
400 #/responses/BadRequest

Uses default content-types: application/json

property type value(s)
errors [object]
property type value(s)
status number
title string
detail string
source object
property type
pointer string

Raw view export for a given time period

GET /views

This endpoint lists every 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 behaviour 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.

Request Parameters

name description type data type required annotation
Authorization JWT token header string yes #/parameters/authParameter
date_time_from Start date and time for a period in ISO8601 format. If you do not specify a timezone offset, the time is considered as America/Los Angeles. query string true #/parameters/dateTimeFromQueryParameter
date_time_to End date and time for a period in ISO8601 format. If you do not specify a timezone offset, the time is considered as America/Los Angeles. query string true #/parameters/dateTimeToQueryParameter
list_unfinished_segments Flag for including unfinished segments in the result query boolean,
default value: true
#/parameters/unfinishedParameter
inclusive_range This flag controls the behaviour of the date and time range filter query boolean,
default value: true
#/parameters/inclusiveRangeParameter
_page Defines the page to get query number,
{ x ∈ ℝ | x ≥ 1 }
default value: 1
#/parameters/offestParameter
_limit Defines how many resources to get query number,
{ x ∈ ℝ | 1 ≤ x ≤ 10000 }
default value: 10
#/parameters/limitParameter

Responses

200 #/responses/ViewList

Uses default content-types: application/json

property type value(s)
resources [object] View
pagination object
property type value(s)
count number
self object
property type
href string
first object
property type
href string
prev object
property type
href string
next object
property type
href string
last object
property type
href string

Example for application/json

{
    "pagination": {
        "count": 10,
        "first": {
            "href": "/views?_page=1&_limit=10"
        },
        "last": {
            "href": "/views?_page=10&_limit=10"
        },
        "next": {
            "href": "/views?_page=2&_limit=10"
        },
        "prev": null,
        "self": {
            "href": "/views?_page=1&_limit=10"
        }
    },
    "resources": [
        {
            "attributes": {
                "city": "Budapest",
                "client_id": "13602851710424434669",
                "content_id": "112342345",
                "content_type": "live",
                "country": "HU",
                "finished_at": "2018-07-16T19:20:42+01:00",
                "from": 0,
                "is_mobile_view": true,
                "started_at": "2018-07-16T19:20:30+01:00",
                "to": 0,
                "view_id": "4bfc69b5-1320-4a44-a8d6-1fe1f397fb94",
                "view_session_id": "7f66d911:8b7aa82c",
                "view_type": "offsite",
                "viewer_identifier": "some.viewer@example.com"
            },
            "type": "View"
        }
    ]
}
400 #/responses/BadRequest

Uses default content-types: application/json

property type value(s)
errors [object]
property type value(s)
status number
title string
detail string
source object
property type
pointer string

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

GET /views/{content_type}

Request Parameters

name description type data type required annotation
Authorization JWT token header string yes #/parameters/authParameter
content_type Type of the content eg. Recorded path string,
x ∈ { live , recorded }
yes #/parameters/contentTypeParameter
content_id A list of comma separated IDs query integer #/parameters/contentTypeParameter
date_time_from Start date and time for a period in ISO8601 format query string true #/parameters/dateTimeFromQueryParameter
date_time_to End date and time for a period in ISO8601 format query string true #/parameters/dateTimeToQueryParameter
list_unfinished_segments Flag for including unfinished segments in the result query boolean,
default value: true
#/parameters/unfinishedParameter
inclusive_range This flag controls the behaviour of the date and time range filter query boolean,
default value: true
#/parameters/inclusiveRangeParameter
_page Defines the page to get query number,
{ x ∈ ℝ | x ≥ 1 }
default value: 1
#/parameters/offestParameter
_limit Defines how many resources to get query number,
{ x ∈ ℝ | 1 ≤ x ≤ 10000 }
default value: 10
#/parameters/limitParameter

Responses

200 #/responses/ViewList

Uses default content-types: application/json

property type value(s)
resources [object] View
pagination object
property type value(s)
count number
self object
property type
href string
first object
property type
href string
prev object
property type
href string
next object
property type
href string
last object
property type
href string

Example for application/json

{
    "pagination": {
        "count": 10,
        "first": {
            "href": "/views?_page=1&_limit=10"
        },
        "last": {
            "href": "/views?_page=10&_limit=10"
        },
        "next": {
            "href": "/views?_page=2&_limit=10"
        },
        "prev": null,
        "self": {
            "href": "/views?_page=1&_limit=10"
        }
    },
    "resources": [
        {
            "attributes": {
                "city": "Budapest",
                "client_id": "13602851710424434669",
                "content_id": "112342345",
                "content_type": "live",
                "country": "HU",
                "finished_at": "2018-07-16T19:20:42+01:00",
                "from": 0,
                "is_mobile_view": true,
                "started_at": "2018-07-16T19:20:30+01:00",
                "to": 0,
                "view_id": "4bfc69b5-1320-4a44-a8d6-1fe1f397fb94",
                "view_session_id": "7f66d911:8b7aa82c",
                "view_type": "offsite",
                "viewer_identifier": "some.viewer@example.com"
            },
            "type": "View"
        }
    ]
}
400 #/responses/BadRequest

Uses default content-types: application/json

property type value(s)
errors [object]
property type value(s)
status number
title string
detail string
source object
property type
pointer string

Parameter definitions

key name description type data type required
granularityParameter granularity The granularity of the breakdown query string,
x ∈ { month (default), day, hour, minute }
true
dimensionParameter dimension The dimension of the breakdown path string,
x ∈ { month, day, hour, location, device, view-source }
true
contentTypeParameter content_type Type of the content eg. Recorded path string,
x ∈ { live, recorded }
true
idsParameter content_id A list of comma separated IDs query integer
dateTimeFromQueryParameter date_time_from Start date and time for a period in ISO8601 format query string true
dateTimeToQueryParameter date_time_to End date and time for a period in ISO8601 format query string true
viewerIdSearchStringQueryParameter viewer_identifier Filter for viewer identifiers containing this string query string
unfinishedParameter list_unfinished_segments Flag for including unfinished segments in the result query boolean,
default value: true
inclusiveRangeParameter inclusive_range This flag controls the behaviour of the date and time range filter query boolean
default value: true
offestParameter _page Defines the page to get query number,
{ x ∈ ℝ | x ≥ 1 },
default value: 1
limitParameter _limit Defines how many resources to get query number,
{ x ∈ ℝ | 1 ≤ x ≤ 10000 }
default value: 10
authParameter Authorization JWT token header string true

Response definitions

BadRequest

Bad request

property type value(s)
errors [object]
property type value(s)
status number
title string
detail string
source object
property type
pointer string

ViewList

OK response

property type value(s)
resources [object] View
pagination object
property type value(s)
count number
self object
property type
href string
first object
property type
href string
prev object
property type
href string
next object
property type
href string
last object
property type
href string

Example for application/json

{
    "pagination": {
        "count": 10,
        "first": {
            "href": "/views?_page=1&_limit=10"
        },
        "last": {
            "href": "/views?_page=10&_limit=10"
        },
        "next": {
            "href": "/views?_page=2&_limit=10"
        },
        "prev": null,
        "self": {
            "href": "/views?_page=1&_limit=10"
        }
    },
    "resources": [
        {
            "attributes": {
                "city": "Budapest",
                "client_id": "13602851710424434669",
                "content_id": "112342345",
                "content_type": "live",
                "country": "HU",
                "finished_at": "2018-07-16T19:20:42+01:00",
                "from": 0,
                "is_mobile_view": true,
                "started_at": "2018-07-16T19:20:30+01:00",
                "to": 0,
                "view_id": "4bfc69b5-1320-4a44-a8d6-1fe1f397fb94",
                "view_session_id": "7f66d911:8b7aa82c",
                "view_type": "offsite",
                "viewer_identifier": "some.viewer@example.com"
            },
            "type": "View"
        }
    ]
}

ViewerTrackingViewerList

OK response

property type value(s)
resources [object] Viewer
pagination object
property type value(s)
count number
self object
property type
href string
first object
property type
href string
prev object
property type
href string
next object
property type
href string
last object
property type
href string

Example for application/json

{
"pagination": {
    "count": 10,
    "first": {
        "href": "/views?_page=1&_limit=1"
    },
    "last": {
        "href": "/views?_page=10&_limit=1"
    },
    "next": {
        "href": "/views?_page=2&_limit=1"
    },
    "prev": null,
    "self": {
        "href": "/views?_page=1&_limit=1"
    }
},
"resources": [
    {
        "attributes": {
            "last_activity": "2018-07-16T19:20:30+01:00",
            "segments": [
                {
                    "city": "Budapest",
                    "client_id": "8776986273576598258658",
                    "content_id": 77569623,
                    "content_type": "live",
                    "country": "HU",
                    "finished_at": "2018-07-16T19:20:40+01:00",
                    "from": 0,
                    "id": "4bfc69b5-1320-4a44-a8d6-1fe1f397fb94",
                    "is_mobile_view": false,
                    "started_at": "2018-07-16T19:20:30+01:00",
                    "to": 0,
                    "view_session_id": "7f66d911:8b7aa82c",
                    "view_type": "onsite"
                }
            ],
            "videos_watched": 10,
            "viewer_identifier": "some.viewer@example.com"
        },
        "type": "Viewer"
    }
]
}

Schema definitions

DeviceInfo (object)

Device information parsed from the user agent string provided by the viewer's client.

Properties
name type data type description
browser object always present
browser.family string always present specifies the User-Agent's family
browser.major string nullable major version number/info of the browser family
browser.minor string nullable minor version number/info of the browser family
browser.patch string nullable patch version number/info of the browser family
os object always present
os.family string always present specifies the OS
os.major string nullable major version number/info of OS
os.minor string nullable minor version number/info of the OS
os.patch string nullable patch version number/info of the OS
os.patch_minor string nullable patchMinor version number/info of the OS
device object always present
device.family string always present specifies the device family
device.brand string nullable brand info of the Device
device.model string nullable model number/info of the Device
Example

"browser": {
    "family": "Chrome",
    "major": "70",
    "minor": "0",
    "patch": "3538"
},
"device": {
    "brand": null,
    "family": "Other",
    "model": null
},
"os": {
    "family": "Mac OS X",
    "major": "10",
    "minor": "14",
    "patch": "1",
    "patch_minor": null
}
        

Segment (object)

One view segment on a content

Properties
name type data type description
id string uuid
content_type string x ∈ { live , recorded } Watched content type
content_id integer
started_at string date-time Start date and time in ISO8601 format
finished_at string date-time 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
client_id string Idetifier of the player client
view_session_id string Player session identifier. Every playing session has a different identifier.
country string
city string
is_mobile_view boolean
view_type string x ∈ { onsite , offsite }
device_info object DeviceInfo Device information parsed from the viewer's user agent.
Example
{
    "city": "Budapest",
    "client_id": "13602851710424434669",
    "content_id": "112342345",
    "content_type": "live",
    "country": "HU",
    "finished_at": "2018-07-16T19:20:42+01:00",
    "from": 0,
    "id": "4bfc69b5-1320-4a44-a8d6-1fe1f397fb94",
    "is_mobile_view": true,
    "started_at": "2018-07-16T19:20:30+01:00",
    "to": 0,
    "view_session_id": "7f66d911:8b7aa82c",
    "view_type": "offsite",
    "device_info": {
        "browser": {
            "family": "Chrome",
            "major": "70",
            "minor": "0",
            "patch": "3538"
        },
        "device": {
            "brand": null,
            "family": "Other",
            "model": null
        },
        "os": {
            "family": "Mac OS X",
            "major": "10",
            "minor": "14",
            "patch": "1",
            "patch_minor": null
        }
    }
}

View (object)

One view segment on a content

Properties
name type data type description
type string
attributes object
name type data type description
view_id string uuid
content_type string x ∈ { live , recorded } Watched content type
content_id integer
started_at string date-time Start date and time in ISO8601 format
finished_at string date-time 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
viewer_identifier string Viewer identifier string. It can be an e-mail or any string representing a viewer
country string
city string
is_mobile_view boolean
view_type string x ∈ { onsite , offsite }
client_id string Idetifier of the player client
view_session_id string Player session identifier. Every playing session has a different identifier.
device_info object DeviceInfo Device information parsed from the viewer's user agent.
Example
{
    "attributes": {
        "city": "Budapest",
        "client_id": "13602851710424434669",
        "content_id": "112342345",
        "content_type": "live",
        "country": "HU",
        "finished_at": "2018-07-16T19:20:42+01:00",
        "from": 0,
        "is_mobile_view": true,
        "started_at": "2018-07-16T19:20:30+01:00",
        "to": 0,
        "view_id": "4bfc69b5-1320-4a44-a8d6-1fe1f397fb94",
        "view_session_id": "7f66d911:8b7aa82c",
        "view_type": "offsite",
        "viewer_identifier": "some.viewer@example.com",
        "device_info": {
            "browser": {
                "family": "Chrome",
                "major": "70",
                "minor": "0",
                "patch": "3538"
            },
            "device": {
                "brand": null,
                "family": "Other",
                "model": null
            },
            "os": {
                "family": "Mac OS X",
                "major": "10",
                "minor": "14",
                "patch": "1",
                "patch_minor": null
            }
        }
    },
    "type": "View"
}

Viewer (object)

One view segment on a content

Properties
name type data type description
type string
attributes object
name type data type description
viewer_identifier string Viewer identifier string. It can be an e-mail or any string representing a viewer
videos_watched integer
last_activity string date-time Last activity recorded from the viewer
segments [object] [Segment] Collection of view segments
Example
{
        "attributes": {
            "last_activity": "2018-07-16T19:20:30+01:00",
            "segments": [
            ],
            "videos_watched": 10,
            "viewer_identifier": "some.viewer@example.com"
        },
        "type": "Viewer"
}