Analytics API Documentation

Introduction

Base URL

Version: 1.0.0

http://analytics-api.ustream.tv/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. 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 receiving unfinished segments in the result query boolean,
default value: false
#/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 ≤ 1000 }
#/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 receiving unfinished segments in the result query boolean,
default value: false
#/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 ≤ 1000 }
#/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.

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 query string, default value: 3 months before the actual server date #/parameters/dateTimeFromQueryParameter
date_time_to End date and time for a period in ISO8601 format query string, default value: current date #/parameters/dateTimeToQueryParameter
list_unfinished_segments Flag for receiving unfinished segments in the result query boolean,
default value: false
#/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 ≤ 1000 }
#/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, default value: 3 months before the actual server date #/parameters/dateTimeFromQueryParameter
date_time_to End date and time for a period in ISO8601 format query string, default value: current date #/parameters/dateTimeToQueryParameter
list_unfinished_segments Flag for receiving unfinished segments in the result query boolean,
default value: false
#/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 ≤ 1000 }
#/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,
default value: 3 months before the actual server date
dateTimeToQueryParameter date_time_to End date and time for a period in ISO8601 format query string
default value: current date
viewerIdSearchStringQueryParameter viewer_identifier Filter for viewer identifiers containing this string query string
unfinishedParameter list_unfinished_segments Flag for receiving unfinished segments in the result query boolean,
default value: false
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 ≤ 1000 }
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

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 }
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"
    }

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.
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"
    },
    "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"
}