How to get ultra low latency viewer data by using the Wowza Streaming Cloud REST API

Learn how to use the REST API to get viewer data for an ultra low latency stream target in the Wowza Streaming Cloud™ service. Viewer data includes the number and percentage of requests for streaming content from an edge server by country and by protocol.

Note: Ultra low latency streaming is available through Wowza Streaming Cloud with Ultra Low Latency. For more information see How to use Wowza Streaming Cloud for ultra low latency streaming.

Contents


Viewer data parameters
Get viewer data for an ultra low latency 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 ultra low latency stream target.

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 an ultra low latency stream target


To see viewer data for an ultra low latency 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 command 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.
  • Viewer data for ultra low latency streams is available without delay but viewer data for Apple HLS streams isn't available until two hours after the stream ends. Then, it updates approximately hourly and may take up to 48 hours to finalize.

Example request and response

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

The query returns the viewer data for all streams delivered to the ultra low latency stream target in the specified timeframe. If the stream target uses a backup Apple HLS stream, viewer data for both ultra low latency (ull) and Apple HLS (hls) streams is returned. Otherwise, only ultra low latency viewer data is returned. The renditions and rendition_list arrays are empty because Wowza ultra low latency targets don't support adaptive bitrate streams.

{
    "stream_target": {
        "total_unique_viewers": 5,
        "percentage_viewers": 100,
        "seconds_total_viewing_time": 18250,
        "seconds_avg_viewing_time": 3650,
        "percentage_viewing_time": 100,
        "protocols": [
            {
                "ull": {
                    "name": "Ultra Low Latency",
                    "total_unique_viewers": 5,
                    "percentage_viewers": 100,
                    "seconds_total_viewing_time": 18250,
                    "seconds_avg_viewing_time": 3650,
                    "percentage_viewing_time": 100
                }
            }
        ],
        "countries": [
            {
                "US": {
                    "name": "United States of America",
                    "total_unique_viewers": 2,
                    "percentage_viewers": 40,
                    "seconds_total_viewing_time": 9340,
                    "seconds_avg_viewing_time": 4670,
                    "percentage_viewing_time": 51,
                    "protocols": [
                        {
                            "ull": {
                                "name": "Ultra Low Latency",
                                "total_unique_viewers": 2,
                                "percentage_viewers": 100,
                                "seconds_total_viewing_time": 9340,
                                "seconds_avg_viewing_time": 4670,
                                "percentage_viewing_time": 100
                            }
                        }
                    ]
                }
            },
            {
                "MX": {
                    "name": "Mexico",
                    "total_unique_viewers": 1,
                    "percentage_viewers": 20,
                    "seconds_total_viewing_time": 620,
                    "seconds_avg_viewing_time": 620,
                    "percentage_viewing_time": 3,
                    "protocols": [
                        {
                            "ull": {
                                "name": "Ultra Low Latency",
                                "total_unique_viewers": 1,
                                "percentage_viewers": 100,
                                "seconds_total_viewing_time": 620,
                                "seconds_avg_viewing_time": 620,
                                "percentage_viewing_time": 100
                            }
                        }
                    ]
                }
            },
            {
                "BR": {
                    "name": "Brazil",
                    "total_unique_viewers": 1,
                    "percentage_viewers": 20,
                    "seconds_total_viewing_time": 330,
                    "seconds_avg_viewing_time": 330,
                    "percentage_viewing_time": 2,
                    "protocols": [
                        {
                            "ull": {
                                "name": "Ultra Low Latency",
                                "total_unique_viewers": 1,
                                "percentage_viewers": 100,
                                "seconds_total_viewing_time": 330,
                                "seconds_avg_viewing_time": 330,
                                "percentage_viewing_time": 100
                            }
                        }
                    ]
                }
            },
            {
                "--": {
                    "name": "-- (Unknown Country)",
                    "total_unique_viewers": 1,
                    "percentage_viewers": 20,
                    "seconds_total_viewing_time": 7960,
                    "seconds_avg_viewing_time": 7960,
                    "percentage_viewing_time": 44,
                    "protocols": [
                        {
                            "ull": {
                                "name": "Ultra Low Latency",
                                "total_unique_viewers": 1,
                                "percentage_viewers": 100,
                                "seconds_total_viewing_time": 7960,
                                "seconds_avg_viewing_time": 7960,
                                "percentage_viewing_time": 100
                            }
                        }
                    ]
                }
            }
        ],
        "renditions": [],
        "rendition_list": [],
        "country_list": [
            "US",
            "MX",
            "BR",
            "--"
        ]
    }
}

If you're having problems or want to discuss this article, post in our forum.