Viewers

Operations related to viewer analytics.

Fetch viewer analytics data for an account

(Available from version 1.11) This operation returns live and historic viewer data for the account related to the JSON web token used for API authentication. You'll use the query parameters to return live vs historic data, as well as specific types of viewer data.

Querying live data

  1. To get data for currently live streams, do not send from and to values.
  2. Use the include query parameter to specify what data you want to return, including: countries, renditions, devices, and trend data.

If you don't send any query parameters (to, from, or include), the total number of viewers is returned.

Querying historic data

  1. To get data for streams that ran previously, send from and to values.
  2. Use the include query parameter to specify what data you want to return, including: countries, renditions, devices, and trend data.

If you don't send include values, the total number of viewers is returned.

If the time range between from and to query parameters is:

  • Less than 60 minutes, the cache time between responses is 10 seconds.
  • More than 60 minutes, the cache time between responses is 60 seconds.
Request
query Parameters
from
string <date-time>

Use this parameter, along with to, to return historic viewer data.

The start of the range of time you want to view. Specify YYYY-DD-MMT HH:MM:SSZ where HH is a 24-hour clock in UTC. The range queried doesn't include minutes and seconds. If you include minutes and seconds, Wowza Video rounds up to the nearest hour when it is more than 30 minutes. If it is less than 30 minutes, Wowza Video rounds it down to the nearest hour. The maximum difference between from and to is 90 days. If you set the from query parameter without setting the to query parameter, the data returned will reflect 30 days starting at the from date, or data up to to the current day, whichever is shorter.

Example: 2023-01-14T10:31:54.486Z

to
string <date-time>

Use this parameter, along with from, to return historic viewer data.

The end of the range of time you want to view. Specify YYYY-DD-MMT HH:MM:SSZ where HH is a 24-hour clock in UTC. The range queried doesn't include minutes and seconds. If you include minutes and seconds, Wowza Video rounds up to the nearest hour when it is more than 30 minutes. If it is less than 30 minutes, Wowza Video rounds it down to the nearest hour. The maximum difference between from and to is 90 days. If you set the to query parameter without setting the from query parameter, the data returned will be from the past 30 days or from your last invoice date, whichever is shorter.

Example: 2023-02-14T10:31:54.486Z

include
string

Specify the data you want returned in the response. You can send a comma-separated list of values.

Valid values are: countries, renditions, devices, and trend.

Example: countries,trend

Responses
200

Success

Response Schema: application/json
object (account)
viewers
integer <int32>

The total number of unique viewers to download at least one chunk of the stream. A unique viewer is a single IP address; multiple users that share the same IP address are counted once.

object (countries)

An array of viewer countries.

object (renditions)

An array of viewer renditions.

object (devices)

An array of viewer devices.

object (Array of viewer trends)

An array of viewer trend data. The granularity of sampled data changes based on the from and to query values you use:

Requests made for data within the past 30 days, return the following sample intervals:

  • 0 minutes to 3 hours - Samples returned per minute
  • 3 hours, 1 second to 24 hours - Samples returned per hour
  • 24 hours, 1 second to 90 days - Samples returned per day

Defaults: from = last billing date, to = end of current day

object

The time frame represented in the response.

401

Unauthorized

403

Forbidden

404

Not Found

410

Gone

422

Unprocessable Entity

get/analytics/viewers/account
Request samples 
// Using cURL
curl -H "Authorization: Bearer ${WV_JWT}" \
  
  -H "Content-Type: application/json" \
  -X "GET" \
  "${WV_HOST}/api/v1.11/analytics/viewers/account?from=2023-04-14T10:31:54.486Z&to=2023-07-13T10:31:54.486Z&include=countries,renditions,devices"
Response samples
application/json
{
  • "account": {
    },
  • "limits": {
    }
}

Fetch viewer analytics data for a live stream

(Available from version 1.11) This operation returns the live and historic viewer data for a specific live stream. You'll use the query parameters to return live vs historic data, as well as specific types of viewer data.

Querying live data

  1. To get data for currently live streams, do not send from and to values.
  2. Use the include query parameter to specify what data you want to return, including: countries, renditions, devices, and trend data.

If you don't send any query parameters (to, from, or include), the total number of viewers is returned.

Querying historic data

  1. To get data for streams that ran previously, send from and to values.
  2. Use the include query parameter to specify what data you want to return, including: countries, renditions, devices, and trend data.

If you don't send include values, the total number of viewers is returned.

If the time range between from and to query parameters is:

  • Less than 60 minutes, the cache time between responses is 10 seconds.
  • More than 60 minutes, the cache time between responses is 60 seconds.
Request
path Parameters
id
required
string

The unique alphanumeric string that identifies the live stream.

query Parameters
from
string <date-time>

Use this parameter, along with to, to return historic viewer data.

The start of the range of time you want to view. Specify YYYY-DD-MMT HH:MM:SSZ where HH is a 24-hour clock in UTC. The range queried doesn't include minutes and seconds. If you include minutes and seconds, Wowza Video rounds up to the nearest hour when it is more than 30 minutes. If it is less than 30 minutes, Wowza Video rounds it down to the nearest hour. The maximum difference between from and to is 90 days. If you set the from query parameter without setting the to query parameter, the data returned will reflect 90 days starting at the from date, or data up to to the current day, whichever is shorter.

Example: 2023-01-14T10:31:54.486Z

to
string <date-time>

Use this parameter, along with from, to return historic viewer data.

The end of the range of time you want to view. Specify YYYY-DD-MMT HH:MM:SSZ where HH is a 24-hour clock in UTC. The range queried doesn't include minutes and seconds. If you include minutes and seconds, Wowza Video rounds up to the nearest hour when it is more than 30 minutes. If it is less than 30 minutes, Wowza Video rounds it down to the nearest hour. The maximum difference between from and to is 90 days. If you set the to query parameter without setting the from query parameter, the data returned will be from the past 90 days or from your last invoice date, whichever is shorter.

Example: 2023-02-14T10:31:54.486Z

include
string

Specify the data you want returned in the response. You can send a comma-separated list of values.

Valid values are: countries, renditions, devices, and trend.

Example: countries,trend

Responses
200

Success

Response Schema: application/json
object (live_stream)
id
string <int32>

The unique alphanumeric string that identifies the live stream.

viewers
integer <int32>

The total number of unique viewers to download at least one chunk of the stream. A unique viewer is a single IP address; multiple users that share the same IP address are counted once.

object (countries)

An array of viewer countries.

object (renditions)

An array of viewer renditions.

object (devices)

An array of viewer devices.

object (Array of viewer trends)

An array of viewer trend data. The granularity of sampled data changes based on the from and to query values you use:

Requests made for data within the past 30 days, return the following sample intervals:

  • 0 minutes to 3 hours - Samples returned per minute
  • 3 hours, 1 second to 24 hours - Samples returned per hour
  • 24 hours, 1 second to 90 days - Samples returned per day

Defaults: from = last billing date, to = end of current day

object

The time frame represented in the response.

401

Unauthorized

403

Forbidden

404

Not Found

410

Gone

422

Unprocessable Entity

get/analytics/viewers/live_streams/{id}
Request samples 
// Using cURL
curl -H "Authorization: Bearer ${WV_JWT}" \
  
  -H "Content-Type: application/json" \
  -X "GET" \
  "${WV_HOST}/api/v1.11/analytics/viewers/live_streams/tvctq36g?from=2023-04-14T10:31:54.486Z&to=2023-07-13T10:31:54.486Z&include=countries,renditions,devices"
Response samples
application/json
{
  • "live_stream": {
    },
  • "limits": {
    }
}

Fetch viewer analytics data for a VOD stream

(Available from version 1.11) This operation returns the live and historic viewer data for a specific VOD stream. You'll use the query parameters to return live vs historic data, as well as specific types of viewer data.

Querying live data

  1. To get data for currently live streams, do not send from and to values.
  2. Use the include query parameter to specify what data you want to return, including: countries, renditions, devices, and trend data.

If you don't send any query parameters (to, from, or include), the total number of viewers is returned.

Querying historic data

  1. To get data for streams that ran previously, send from and to values.
  2. Use the include query parameter to specify what data you want to return, including: countries, renditions, devices, and trend data.

If you don't send include values, the total number of viewers is returned.

If the time range between from and to query parameters is:

  • Less than 60 minutes, the cache time between responses is 10 seconds.
  • More than 60 minutes, the cache time between responses is 60 seconds.
Request
path Parameters
id
required
string

The unique alphanumeric string that identifies the VOD stream.

query Parameters
from
string <date-time>

Use this parameter, along with to, to return historic viewer data.

The start of the range of time you want to view. Specify YYYY-DD-MMT HH:MM:SSZ where HH is a 24-hour clock in UTC. The range queried doesn't include minutes and seconds. If you include minutes and seconds, Wowza Video rounds up to the nearest hour when it is more than 30 minutes. If it is less than 30 minutes, Wowza Video rounds it down to the nearest hour. The maximum difference between from and to is 90 days. If you set the from query parameter without setting the to query parameter, the data returned will reflect 90 days starting at the from date, or data up to to the current day, whichever is shorter.

Example: 2023-01-14T10:31:54.486Z

to
string <date-time>

Use this parameter, along with from, to return historic viewer data.

The end of the range of time you want to view. Specify YYYY-DD-MMT HH:MM:SSZ where HH is a 24-hour clock in UTC. The range queried doesn't include minutes and seconds. If you include minutes and seconds, Wowza Video rounds up to the nearest hour when it is more than 30 minutes. If it is less than 30 minutes, Wowza Video rounds it down to the nearest hour. The maximum difference between from and to is 90 days. If you set the to query parameter without setting the from query parameter, the data returned will be from the past 90 days or from your last invoice date, whichever is shorter.

Example: 2023-02-14T10:31:54.486Z

include
string

Specify the data you want returned in the response. You can send a comma-separated list of values.

Valid values are: countries, renditions, devices, and trend.

Example: countries,trend

Responses
200

Success

Response Schema: application/json
object (vod_stream)
id
string <int32>

The unique alphanumeric string that identifies the VOD stream.

viewers
integer <int32>

The total number of unique viewers to download at least one chunk of the VOD stream. A unique viewer is a single IP address; multiple users that share the same IP address are counted once.

object (countries)

An array of viewer countries.

object (renditions)

An array of viewer renditions.

object (devices)

An array of viewer devices.

object (Array of viewer trends)

An array of viewer trend data. The granularity of sampled data changes based on the from and to query values you use:

Requests made for data within the past 30 days, return the following sample intervals:

  • 0 minutes to 3 hours - Samples returned per minute
  • 3 hours, 1 second to 24 hours - Samples returned per hour
  • 24 hours, 1 second to 90 days - Samples returned per day

Defaults: from = last billing date, to = end of current day

object

The time frame represented in the response.

401

Unauthorized

403

Forbidden

404

Not Found

410

Gone

422

Unprocessable Entity

get/analytics/viewers/vod_streams/{id}
Request samples 
// Using cURL
curl -H "Authorization: Bearer ${WV_JWT}" \
  
  -H "Content-Type: application/json" \
  -X "GET" \
  "${WV_HOST}/api/v1.11/analytics/viewers/vod_streams/tvctq36g?from=2023-04-14T10:31:54.486Z&to=2023-07-13T10:31:54.486Z&include=countries,renditions,devices"
Response samples
application/json
{
  • "vod_stream": {
    },
  • "limits": {
    }
}

Fetch viewer analytics data for a stream target

(Available from version 1.11) This operation returns the live and historic viewer data for a specific stream target. You'll use the query parameters to return live vs historic data, as well as specific types of viewer data.

Querying live data

  1. To get data for currently live streams, do not send from and to values.
  2. Use the include query parameter to specify what data you want to return, including: countries, renditions, devices, and trend data.

If you don't send any query parameters (to, from, or include), the total number of viewers is returned.

Querying historic data

  1. To get data for streams that ran previously, send from and to values.
  2. Use the include query parameter to specify what data you want to return, including: countries, renditions, devices, and trend data.

If you don't send include values, the total number of viewers is returned.

If the time range between from and to query parameters is:

  • Less than 60 minutes, the cache time between responses is 10 seconds.
  • More than 60 minutes, the cache time between responses is 60 seconds.
Request
path Parameters
id
required
string

The unique alphanumeric string that identifies the stream target.

query Parameters
from
string <date-time>

Use this parameter, along with to, to return historic viewer data.

The start of the range of time you want to view. Specify YYYY-DD-MMT HH:MM:SSZ where HH is a 24-hour clock in UTC. The range queried doesn't include minutes and seconds. If you include minutes and seconds, Wowza Video rounds up to the nearest hour when it is more than 30 minutes. If it is less than 30 minutes, Wowza Video rounds it down to the nearest hour. The maximum difference between from and to is 90 days. If you set the from query parameter without setting the to query parameter, the data returned will reflect 90 days starting at the from date, or data up to to the current day, whichever is shorter.

Example: 2023-01-14T10:31:54.486Z

to
string <date-time>

Use this parameter, along with from, to return historic viewer data.

The end of the range of time you want to view. Specify YYYY-DD-MMT HH:MM:SSZ where HH is a 24-hour clock in UTC. The range queried doesn't include minutes and seconds. If you include minutes and seconds, Wowza Video rounds up to the nearest hour when it is more than 30 minutes. If it is less than 30 minutes, Wowza Video rounds it down to the nearest hour. The maximum difference between from and to is 90 days. If you set the to query parameter without setting the from query parameter, the data returned will be from the past 90 days or from your last invoice date, whichever is shorter.

Example: 2023-02-14T10:31:54.486Z

include
string

Specify the data you want returned in the response. You can send a comma-separated list of values.

Valid values are: countries, renditions, devices, and trend.

Example: countries,trend

Responses
200

Success

Response Schema: application/json
object (stream_target)
id
string <int32>

The unique alphanumeric string that identifies the stream target.

viewers
integer <int32>

The total number of unique viewers to download at least one chunk of the stream at the target (for HTTP streams). A unique viewer is a single IP address; multiple users that share the same IP address are counted once.

object (countries)

An array of viewer countries.

object (renditions)

An array of viewer renditions.

object (devices)

An array of viewer devices.

object (Array of viewer trends)

An array of viewer trend data. The granularity of sampled data changes based on the from and to query values you use:

Requests made for data within the past 30 days, return the following sample intervals:

  • 0 minutes to 3 hours - Samples returned per minute
  • 3 hours, 1 second to 24 hours - Samples returned per hour
  • 24 hours, 1 second to 90 days - Samples returned per day

Defaults: from = last billing date, to = end of current day

object

The time frame represented in the response.

401

Unauthorized

403

Forbidden

404

Not Found

410

Gone

422

Unprocessable Entity

get/analytics/viewers/stream_targets/{id}
Request samples 
// Using cURL
curl -H "Authorization: Bearer ${WV_JWT}" \
  
  -H "Content-Type: application/json" \
  -X "GET" \
  "${WV_HOST}/api/v1.11/analytics/viewers/stream_targets/tvctq36g?from=2023-04-14T10:31:54.486Z&to=2023-07-13T10:31:54.486Z&include=countries,renditions,devices"
Response samples
application/json
{
  • "stream_target": {
    },
  • "limits": {
    }
}

Fetch viewer analytics data for the most viewed live streams

(Available from version 1.11) This operation returns viewer data for the top 100 live streams in an account.

Querying data

To get viewer data for the top 100 streams that ran previously, send from and to values.

If you do not send from and to values, the last five minutes' worth of live stream viewer data is returned.

If the time range between from and to query parameters is:

  • Less than 60 minutes, the cache time between responses is 10 seconds.
  • More than 60 minutes, the cache time between responses is 60 seconds.
Request
query Parameters
from
string <date-time>

Use this parameter, along with to, to return historic viewer data.

The start of the range of time you want to view. Specify YYYY-DD-MMT HH:MM:SSZ where HH is a 24-hour clock in UTC. The range queried doesn't include minutes and seconds. If you include minutes and seconds, Wowza Video rounds up to the nearest hour when it is more than 30 minutes. If it is less than 30 minutes, Wowza Video rounds it down to the nearest hour. The maximum difference between from and to is 90 days. If you set the from query parameter without setting the to query parameter, the data returned will reflect 30 days starting at the from date, or data up to to the current day, whichever is shorter.

Example: 2023-01-14T10:31:54.486Z

to
string <date-time>

Use this parameter, along with from, to return historic viewer data.

The end of the range of time you want to view. Specify YYYY-DD-MMT HH:MM:SSZ where HH is a 24-hour clock in UTC. The range queried doesn't include minutes and seconds. If you include minutes and seconds, Wowza Video rounds up to the nearest hour when it is more than 30 minutes. If it is less than 30 minutes, Wowza Video rounds it down to the nearest hour. The maximum difference between from and to is 90 days. If you set the to query parameter without setting the from query parameter, the data returned will be from the past 30 days or from your last invoice date, whichever is shorter.

Example: 2023-02-14T10:31:54.486Z

Responses
200

Success

Response Schema: application/json
required
Array of objects (live_streams)
object

The time frame represented in the response.

401

Unauthorized

403

Forbidden

404

Not Found

410

Gone

422

Unprocessable Entity

get/analytics/viewers/live_streams
Request samples 
// Using cURL
curl -H "Authorization: Bearer ${WV_JWT}" \
  
  -H "Content-Type: application/json" \
  -X "GET" \
  "${WV_HOST}/api/v1.11/analytics/viewers/live_streams?from=2023-04-14T10:31:54.486Z&to=2023-07-13T10:31:54.486Z"
Response samples
application/json
{
  • "live_streams": [
    ],
  • "limits": {
    }
}

Fetch viewer analytics data for the most viewed VOD streams

(Available from version 1.11) This operation returns viewer data for the top 100 VOD streams in an account.

Querying data

To get viewer data for the top 100 streams that ran previously, send from and to values.

If you do not send from and to values, the last five minutes' worth of VOD stream viewer data is returned.

If the time range between from and to query parameters is:

  • Less than 60 minutes, the cache time between responses is 10 seconds.
  • More than 60 minutes, the cache time between responses is 60 seconds.
Request
query Parameters
from
string <date-time>

Use this parameter, along with to, to return historic viewer data.

The start of the range of time you want to view. Specify YYYY-DD-MMT HH:MM:SSZ where HH is a 24-hour clock in UTC. The range queried doesn't include minutes and seconds. If you include minutes and seconds, Wowza Video rounds up to the nearest hour when it is more than 30 minutes. If it is less than 30 minutes, Wowza Video rounds it down to the nearest hour. The maximum difference between from and to is 90 days. If you set the from query parameter without setting the to query parameter, the data returned will reflect 30 days starting at the from date, or data up to to the current day, whichever is shorter.

Example: 2023-01-14T10:31:54.486Z

to
string <date-time>

Use this parameter, along with from, to return historic viewer data.

The end of the range of time you want to view. Specify YYYY-DD-MMT HH:MM:SSZ where HH is a 24-hour clock in UTC. The range queried doesn't include minutes and seconds. If you include minutes and seconds, Wowza Video rounds up to the nearest hour when it is more than 30 minutes. If it is less than 30 minutes, Wowza Video rounds it down to the nearest hour. The maximum difference between from and to is 90 days. If you set the to query parameter without setting the from query parameter, the data returned will be from the past 30 days or from your last invoice date, whichever is shorter.

Example: 2023-02-14T10:31:54.486Z

Responses
200

Success

Response Schema: application/json
required
Array of objects (vod_streams)
object

The time frame represented in the response.

401

Unauthorized

403

Forbidden

404

Not Found

410

Gone

422

Unprocessable Entity

get/analytics/viewers/vod_streams
Request samples 
// Using cURL
curl -H "Authorization: Bearer ${WV_JWT}" \
  
  -H "Content-Type: application/json" \
  -X "GET" \
  "${WV_HOST}/api/v1.11/analytics/viewers/vod_streams?from=2023-04-14T10:31:54.486Z&to=2023-07-13T10:31:54.486Z"
Response samples
application/json
{
  • "vod_streams": [
    ],
  • "limits": {
    }
}
© 2007-2024 Wowza Media Systems, ™ LLC. All rights reserved.   Security & Privacy Policy | Legal | System Status