Get viewer data for a Wowza CDN stream target with the Wowza Streaming Cloud REST API

Learn how to use the REST API to get viewer data for Wowza CDN stream targets in the Wowza Streaming Cloud™ service. Viewer data includes the number of requests to play content from the stream target, and breakdowns of requests by country, protocol, and adaptive-bitrate rendition.

Note: Viewer data is available about two hours after a transcoder stops running and then updates approximately hourly. Total unique viewers, however, begins to update approximately three hours after the stream starts and may take up to 48 hours to finalize after the stream ends.

To learn how to get viewer data for an ultra low latency stream target, see Get ultra low latency viewer data with the Wowza Streaming Cloud REST API.

Contents


Viewer data parameters
Get viewer data for a Wowza CDN stream target

Viewer data parameters


Parameter Data Type Description
from datetime The start of the range of time you want to view. Specify YYYY-MM-DD HH:MM:SS where HH is a 24-hour clock in UTC. The default time range is from the last billing date to the end of the current day.
stream_target_id string

The unique alphanumeric string that identifies the stream target.

Note: To see viewer data, the stream target must be one whose type is WowzaStreamTarget.

to datetime The end of the range of time you want to view. Specify YYYY-MM-DD HH:MM:SS where HH is a 24-hour clock in UTC. The default time range is from the last billing date to the end of the current day.

Get viewer data for a Wowza CDN stream target


To see viewer data for a Wowza CDN stream target, call the resource

https://api.cloud.wowza.com/api/[version]/usage/viewer_data/stream_targets/[stream_target_id]
Notes:
  • For [key], substitute your API key or your access key as appropriate. For more information, see Locating and using API and access keys.
  • For [version], substitute the version number of the API that you're using. For the current version, use v1.2.
  • The --data-urlencode option in the example curl commands replaces unprintable and special characters, such as spaces, curly brackets, forward slashes, and semicolons, with ASCII-safe, unambiguous characters that are understood across the Internet.

Example request and response

curl -G -H 'wsc-api-key: [key]' -H 'wsc-access-key: [key]' -H 'Content-Type: application/json' --data-urlencode 'from=2015-07-01 12:00:00' --data-urlencode 'to=2015-07-16 12:00:00' https://api.cloud.wowza.com/api/[version]/usage/viewer_data/stream_targets/1234abcd/

The query returns the viewer data for the stream target in the specified timeframe and looks something like this:

{
    "stream_target": {
        "total_unique_viewers": 17058,
        "percentage_viewers": 100,
        "seconds_total_viewing_time": 44925498,
        "seconds_avg_viewing_time": 2633.690819556806,
        "percentage_viewing_time": 100,
        "protocols": [{
                "hls": {
                    "name": "Apple HLS",
                    "total_unique_viewers": 11397,
                    "percentage_viewers": 67,
                    "seconds_total_viewing_time": 20230110,
                    "seconds_avg_viewing_time": 1775.0381679389313,
                    "percentage_viewing_time": 45
                }
            },
            {
                "hds": {
                    "name": "Adobe HDS",
                    "total_unique_viewers": 6693,
                    "percentage_viewers": 39,
                    "seconds_total_viewing_time": 24695388,
                    "seconds_avg_viewing_time": 3689.7337516808607,
                    "percentage_viewing_time": 55
                }
            },
            {
                "rtmp": {
                    "name": "RTMP",
                    "total_unique_viewers": 0,
                    "percentage_viewers": 0,
                    "seconds_total_viewing_time": 0,
                    "seconds_avg_viewing_time": 0,
                    "percentage_viewing_time": 100
                }
            }
        ],
        "countries": [{
                "US": {
                    "name": "United States of America",
                    "...": "...",
                    "protocols": [{
                            "hls": {
                                "name": "Apple HLS",
                                "...": "..."
                            }
                        },
                        {
                            "hds": {
                                "name": "Adobe HDS",
                                "...": "..."
                            }
                        },
                        {
                            "rtmp": {
                                "name": "RTMP",
                                "...": "..."
                            }
                        }
                    ]
                }
            },
            {
                "CA": {
                    "name": "Canada",
                    "...": "..."
                }
            }
        ],
        "renditions": [{
            "448": {
                "countries": [{
                    "US": {
                        "name": "United States of America",
                        "...": "..."
                    }
                }],
                "protocols": [{
                            "hls": {
                                "name": "Apple HLS",
                                "...": "..."
                            }
                        },
                        {
                            "hds": {
                                "name": "Adobe HDS",
                                "...": "..."
                            }
                        },
                        {
                            "rtmp": {
                                "name": "RTMP",
                                "...": "..."
                            }
                        }
                ],
                "total_unique_viewers": 12453,
                "percentage_viewers": 100,
                "percentage_viewing_time": 100,
                "seconds_avg_viewing_time": 387.3736449048422,
                "seconds_total_viewing_time": 4823964
            },
            "640": {
                "...": "..."
            }
        }],
        "rendition_list": [
            4128,
            2728,
            1728,
            1152,
            640,
            448
        ],
        "country_list": [
            "AU",
            "CA",
            "CH",
            "CZ",
            "DE",
            "FI",
            "GB",
            "IE",
            "IL",
            "IN",
            "MX",
            "PL",
            "SE",
            "US"
        ]
    }
}