Analytics API: Live Metrics

This topic explains the analytics metrics available for Live streams.

Introduction

Playback metrics for Live streams served by the Brightcove Live service are available in realtime, through the Analytics API. This data is captured for live streams only; VOD playback is not included.

The base URL for the Analytics API is:
https://analytics.api.brightcove.com

The API provides Live stream metrics via 2 endpoints:

  • /v1/timeseries
  • /v1/events

Both query the same data set, but aggregate the results differently. This document describes the usage and syntax of each.

Metrics

These are the metrics available via the Live endpoints. Queries may request multiple metrics.

Metric Description
alive_ss_ad_start Server-side ad impressions
ccu Unique sessions; count of distinct (fingerprint + Session)
fingerprint_count Unique devices; count of distinct fingerprints (see below)
video_impression Number of times video was loaded into player
video_seconds_viewed Total seconds watched by all viewers
video_view Stream starts (not unique)

For unique tracking, we assign a fingerprint to each device by combining (Remote IP + User-Agent + Player). Note that we don’t use an actual hardware ID from the device itself - this reduces accuracy, but keeps us privacy-compliant.

Dimensions

The following combinations are supported as dimensions and where filter keys:

  • video
  • video, country
  • video, device_type

Query Parameters

Both Live endpoints share some common parameters that control the scope and grouping of the query.

Parameter Syntax Required Default Description
dimensions <dim1>,<dim2>,... Y - Query dimensions (GROUP BY)
metrics <metric1>,<metric2>,... Y - One or more metrics to report
where <dim1>==<value1>;... Y - One or more query filters; must include at least 1 video
from <epoch> N 32 days from now Time range begin
to <epoch> N now Time range end

Time Series

The /v1/timeseries endpoint returns a list of points along a timeline, with the value of the requested metric at each point in time. Points are 1 minute buckets by default, but can be changed via a parameter.

In this context, Unique metrics (ccu, fingerprint_count) indicate the maximum value at any time during each bucket. So a query with bucket_duration=1d will return the maximum concurrency for each day, while a query with bucket_limit=1 will return the maximum concurrency at any point in the stream.

URI

/v1/timeseries/accounts/{{account_id}}

Additional Parameters

Parameter Syntax Required Default Description
bucket_duration <n>m (minutes)
<n>h (hours)
<n>d (days)		 N 1m Duration represented by each point. 1d is 24 hours, not a Calendar day.
bucket_limit <n> N - Number of points to return. Use either bucket_duration or bucket_limit, but not both together.

Response

{
"<metric1>": {
"data": [
  {
    "dimensions": {
        "account": "<account>",
        "<dim1>": "<key1>",
        ...
        "<dimN>": "<keyN>"
      },
    "points": [
      {
        "timestamp": <bucket1>,
        "value": <value1>
      },
      ...,
      {
        "timestamp": <bucketN>,
        "value": <valueN>
      },
    ]
  }
]
},
"<metric2>": {
...
},
...
}

Events

The /v1/events endpoint returns metric totals for all or part of a Live video stream.

In this context, Unique metrics (ccu, fingerprint_count) represent the total value over the query range. So for example, a query without from/to parameters will return the total number of unique sessions (ccu) and/or devices (fingerprint_count) for the entire stream.

URI

/v1/events/accounts/{{account_id}}

Additional Parameters

none

Response

{
"data": [
{
  "dimensions": {
    "account": "<account>",
    "<dim1>": "<key1>",
    ...
    "<dimN>": "<keyN>"
  },
  "totals": {
    "<metric1>": <value1>,
    ...
    "<metricN>": <valueN>
  }
}
]
}

Export

The Events endpoint also provides a downloadable report:

/v1/events/accounts/{{account_id}}/videos/{{video_id}}/export?format=xlsx

The response is an XLSX file with Live metrics on 4 Sheets:

  • Summary
  • Concurrent users
  • Views by Device Type
  • Views by Geography

Usage Examples

For all these examples, we’ll use Account 1234, Video 5555, and assume a current time of 12:00:00 PM UTC on Feb 15th, 2020.

Get the current Viewer count (CCU) for a Live Stream or Channel

Set from to at least 2 minutes ago (11:58 AM), and use the last point in the response.

/v1/timeseries/accounts/1234?dimensions=video&metrics=ccu&where=video==5555&from=1581767880000

Get CCU graph points for a Live stream over the past 24 hours

Zoom in (1-minute points)

/v1/timeseries/accounts/1234?dimensions=video&metrics=ccu&where=video==5555&from=1581681600000&bucket_duration=1m

Zoom out (1-hour points)

/v1/timeseries/accounts/1234?dimensions=video&metrics=ccu&where=video==5555&from=1581681600000&bucket_duration=1h

Get the maximum CCU per day for a Live channel over the past 7 days

/v1/timeseries/accounts/1234?dimensions=video&metrics=ccu&where=video==5555&from=1581206400000&bucket_duration=7d

Get the maximum CCU at any time during a Live stream

/v1/timeseries/accounts/1234?dimensions=video&metrics=ccu&where=video==5555&bucket_limit=1

Get the total Unique Viewers and Seconds Viewed for multiple Live streams

Video 5555 has completed; numbers are final. Video 5556 is still active; numbers are running totals.

/v1/events/accounts/1234?dimensions=video&metrics=fingerprint_count,video_seconds_viewed&where=video==5555,5556

Get the Viewership and Ad totals for an hour-long program on a Live channel<

Program aired from 10:00 AM until 11:00 AM (UTC)

/v1/events/accounts/1234?dimensions=video&metrics=alive_ss_ad_start,video_view,fingerprint_count&where=video==5555&from=1581760800000&to=1581764399999

Get Viewership by Country for the duration of a Live stream

/v1/events/accounts/1234?dimensions=video,country&metrics=video_view,fingerprint_count&where=video==5555