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

Use the REST API to get viewer data for Wowza 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.

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.
wowza_stream_target_id string

The unique alphanumeric string that identifies the Wowza 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 a Wowza stream target


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

https://api.cloud.wowza.com/api/[version]/usage/viewer_data/stream_targets/[wowza_stream_target_id]

Notes:
  • To authenticate API requests, use HMAC authentication for production environments. For testing or proof of concept purposes only, use API key and access key authentication.
  • The curl examples below use environment variables. See Using cURL for more information on how to set these up.
  • 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 -X GET \
-H "Content-Type: application/json" \
-H "wsc-api-key: ${WSC_API_KEY}" \
-H "wsc-access-key: ${WSC_ACCESS_KEY}" \
--data-urlencode 'from=2015-07-01 12:00:00' \
--data-urlencode 'to=2015-07-16 12:00:00' \ 
"${WSC_HOST}/api/${WSC_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"
        ]
    }
}