Analytics API: Unique Users

Product(s)
Video Cloud
Role(s)
API Developer
API(s)
Analytics API

In this topic, you will learn about how to obtain data on unique users via the Analytics API and how unique users are calulated.

Introduction

The unique_users field which gives customers an estimated number of unique viewers per day at the account level. The data is returned in a field which is called daily_unique_viewers. This field is only available at the account level. See Overview: Data Collection API for more information on how user data is collected and used.

Note that unique users data is returned only for reconciled data.

Sample calls

Here is a sample call for a user report for a day, using the day dimension:

https://analytics.api.brightcove.com/v1/data?accounts=789967572001&dimensions=date&from=2014-07-09&to=2014-07-22&limit=10&format=json&fields=daily_unique_viewers,date,video_view

Sample output:

{
  "item_count": 14,
  "items": [
    {
      "daily_unique_viewers": 73,
      "date": "2014-07-09",
      "video_view": 454
    },
    {
      "daily_unique_viewers": 203,
      "date": "2014-07-10",
      "video_view": 287
    },
    {
      "daily_unique_viewers": 150,
      "date": "2014-07-15",
      "video_view": 257
    },
    {
      "daily_unique_viewers": 170,
      "date": "2014-07-12",
      "video_view": 195
    },
    {
      "daily_unique_viewers": 120,
      "date": "2014-07-14",
      "video_view": 166
    },
    {
      "daily_unique_viewers": 118,
      "date": "2014-07-11",
      "video_view": 155
    },
    {
      "daily_unique_viewers": 95,
      "date": "2014-07-16",
      "video_view": 150
    },
    {
      "daily_unique_viewers": 89,
      "date": "2014-07-17",
      "video_view": 136
    },
    {
      "daily_unique_viewers": 57,
      "date": "2014-07-18",
      "video_view": 132
    },
    {
      "daily_unique_viewers": 99,
      "date": "2014-07-13",
      "video_view": 108
    }
  ],
  "summary": {
    "video_view": 2334
  },
  "account": "789967572001"
}

Based on that results set, this entry...

{
  "daily_unique_viewers": 73,
  "date": "2014-07-09",
  "video_view": 454
},

...means that this account had 454 views from 73 estimated unique users on July 9, 2014.

Span Multiple Days Is Average

If you do a request which spans multiple days, like this:

https://analytics.api.brightcove.com/v1/data?accounts=789967572001&dimensions=account&from=2014-07-09&to=2014-07-22&limit=10&format=json&fields=daily_unique_viewers,video_view

The response will contain the average value of daily_unique_viewers for the time period.

{
  "item_count": 1,
  "items": [
    {
      "account": "789967572001",
      "daily_unique_viewers": 99,
      "video_view": 2334
    }
  ],
  "summary": {
    "video_view": 2334
  },
  "account": "789967572001"
}

Availability of data

The uniques estimate happens in the batch processing system, which means this daily_unique_viewers value is not available in real time. The value of daily_unique_viewers will not be available for 3-5 days after the day being measured has passed. If you call the API and get a NULL response that means that the data is not available yet.

Identifying Users

Video Cloud Analytics uses a string composed of the Source IP address + the User-Agent String as the unique identifier for users.

Total unique users

Because storing unique identifiers for all users is not feasible, we use an algorithm to estimate the total users for an account.

That means if you know the exact number of viewers and compare that to our number, you will see a small discrepancy. This error rate increases as the number of unique viewers increase.