Overview: Audience API

Product(s)
Video Cloud
Role(s)
API Developer
Topic(s)
API Overviews
Audience/Marketing Automation
API(s)
Audience API

In this topic, you will learn about the Audience API. The Audience API allows you to retrieve viewing event and lead data.

Base URL

The base URL for the Audience API is:

https://audience.api.brightcove.com/v1

Account path

In all cases, requests will be made for a specific Video Cloud Account. You will always need to add the term “accounts” followed by your account ID to the base URL:

https://audience.api.brightcove.com/v1/accounts/{account_id} 

Authentication

The Audience API uses the Brightcove OAuth Service to authenticate calls.

You will first need to obtain client credentials (a client_id and client_secret). This is a one-time operation that can be performed using the OAuth Credentials UI. You will need permissions for Audience/Read operations:

Required Permissions
Required Permissions

You can get client credentials directly from the Brightcove OAuth Service using cURL or Postman.

You will also need an access_token, which is obtained using the client_id and client_secret and passed in an Authorization header with your API request:

Authorization: Bearer {access_token}

The access_token expires after five minutes, so you must obtain one for each request, or check to make sure that your token is still valid. See Getting Access Tokens for a detailed explanation of how to get access tokens, including code samples.

Rate limiting

Usage of the API is limited to:

  • 50 requests per second per account
  • 50 requests per second per IP address

Caching

API responses are cached for approximately 5 minutes. To discern whether or not your response was retrieved from cache, look for the X-Cache header which will equal HIT if the response was cached or MISS if it wasn’t cached.

HTTP/1.1 200 OK
Content-Type: application/json; charset=utf-8
Date: Wed, 29 Jun 2016 20:40:07 GMT
X-Cache: MISS
Content-Length: 8178
Connection: keep-alive

Error handling

If an error occurs, the API will respond with one of the following status codes and a corresponding error code in the response body:

Status Code Error Code Description
400 BAD_REQUEST_ERROR Query parameters are invalid
401 UNAUTHORIZED_ERROR The access token is either absent, has expired, or is invalid
404 RESOURCE_NOT_FOUND The URL does not exist
429 REQUEST_THROTTLED_ERROR The user has exceeded the rate limiting policy
500 INTERNAL_ERROR An internal error has occurred
504 GATEWAY_TIMEOUT_ERROR The server timed out while fulfilling your request

Below is a sample response body for an error:

[
   {
    "error_code": "UNAUTHORIZED_ERROR",
    "message": "Permission denied"
   }
]

Parameters

There are several parameters you can add to requests to limit and filter the data retrieved. These apply to all the request types described in the sections that follow.

Filtering results

You can filter the results using the where parameter. The syntax for filters is:

where=field1==value1;field2==value2

For example:

where=video_id==123456789;video_name==test

Commas are treated as logical ORs and semicolons as logical ANDs. For example, where=video_id==1234,5678;video_name=test is interpreted as "where video_id = 1234 OR 5678, AND video_name = test".

Selecting fields to return

A list of fields may be specified in the request to limit the results to that subset of fields. The syntax for fields is:

fields=field1,field4

For example:

fields=video_id,video_name

The fields that you can filter and sort on are detailed for each request type in the sections that follow.

Date ranges

Date ranges can be specified in from and to parameters and are applied to the date that the view event was last updated (the updated_at field). Date ranges can be indicated in the following formats:

  • The text value now which represents the current time
  • Epoch time values in milliseconds, such as 1377047323000
  • Dates expressed in ISO 8601 standard international date format: YYYY-MM-DD format, such as 2013-09-12. For dates expressed in this format:
    • Any date range specified will be interpreted in UTC
    • The time for the date give will be interpreted as midnight ( 00:00:00) on the date specified
  • Relative dates: you can express either of the to and from values relative to the other one in d (days), h (hours), m (minutes), or s (sec). For example:
    • from=2015-01-01&to=31d
    • from=-48h&to=now
    • from=-2d&to=now (will give the same results as the previous example)
    • from=-365d&to=2015-12-31
    • from=-10m&to=now

Paging results

The limit is the number of items to return (default: 25; maximum: 100). offset is the number of items to skip (default: 0). You can use limit and offset together to create an app that pages through the results. Each includes the limit, offset, and count., which you can use to set up iteration over total results. For example, in JavaScript, you could get the total iterations required like this:

// response is the JSON-parsed response from the first request
var totalRequests = Math.ceil(response.count / response.limit)

Retrieving view events

To retrieve view events in an account, perform a GET request to the view_events resource:

https://audience.api.brightcove.com/v1/accounts/{account_id}/view_events

Here is sample request in cURL

curl -i https://audience.api.brightcove.com/v1/accounts/{account_id}/view_events?where=video_id==123&from=-5d&to=now&sort=-created_at \
  -H "Authorization: Bearer {token}"

The response will look like this:

{
    "count": 27,
    "limit": 25,
    "offset": 0,
    "result": [
        {
            "created_at": "2016-04-25T18:30:21.651Z",
            "page_url": "http://players.brightcove.net/1486906377/V1s6NOwRx_default/index.html?videoId=4842718056001",
            "player_id": "V1s6NOwRx",
            "time_watched": 2,
            "updated_at": "2016-04-25T18:30:21.651Z",
            "video_id": "4842718056001",
            "video_name": "Horses Heading to the Track",
            "watched": 19
        },
        {
            "created_at": "2016-04-25T18:31:55.071Z",
            "page_url": "http://players.brightcove.net/1486906377/BkgFuzyhg_default/index.html?videoId=4842718056001",
            "player_id": "BkgFuzyhg",
            "time_watched": 15,
            "updated_at": "2016-04-25T18:32:00.879Z",
            "video_id": "4842718056001",
            "video_name": "Horses Heading to the Track",
            "watched": 99
        }, ...
    }
]

Fields for filtering and selection

All the parameters can be used with view_event requests.

Here is sample request in cURL using the parameters:

curl -i https://audience.api.brightcove.com/v1/accounts/{account_id}/view_events?where=video_id==123&from=-5d&to=now&sort=-created_at \
  -H "Authorization: Bearer {token}"

The following fields are supported for view_event requests when filtering with a where clause or when selecting during a fields clause:

Field Description
video_id Brightcove video ID
video_name Brightcove video name
tracking_id Custom tracking ID
external_id The Marketo, Eloqua or custom GUID
player_id The ID of the Brightcove player that created the view event
page_url The URL of the page where the view event was created
watched Percent watched
time_watched Seconds of the video watched
created_at Creation date
updated_at Last updated date
is_synced A boolean denoting whether or not the view event has been synchronized
event_1 Custom events
event_2
event_3
metric_1 Custom metrics
metric_2
metric_3

Retrieving leads

To retrieve view events in an account, perform a GET request to the view_events resource:

https://audience.api.brightcove.com/v1/accounts/{account_id}/leads

Sample response:

{
    "count": 2,
    "limit": 25,
    "offset": 0,
    "result": [
        {
            "created_at": "2016-06-30T12:57:11.283Z",
            "email_address": "bbailey@brightcove.com",
            "first_name": "Bob",
            "last_name": "Bailey",
            "page_url": "http://players.brightcove.net/1486906377/Hk4TBqzL_default/index.html?videoId=4997275041001",
            "player_id": "Hk4TBqzL",
            "video_id": "4997275041001"
        },
        {
            "created_at": "2016-06-30T12:57:33.301Z",
            "email_address": "rcrooks@brightcove.com",
            "first_name": "Robert",
            "last_name": "Crooks",
            "page_url": "http://players.brightcove.net/1486906377/Hk4TBqzL_default/index.html?videoId=4997275041001",
            "player_id": "Hk4TBqzL",
            "video_id": "4997275041001"
        }
    ]
}

Fields for filtering and selection

All the parameters can be used with leads requests.

Here is sample request in cURL using the parameters:

curl -i https://audience.api.brightcove.com/v1/accounts/{account_id}/leads?where=video_id==123&from=-5d&to=now&sort=-created_at \
  -H "Authorization: Bearer {token}"

The following fields are supported for leads requests when filtering with a where clause or when selecting during a fields clause:

Field Description
video_id Brightcove video ID
external_id The Marketo, Eloqua or custom GUID
player_id The ID of the Brightcove player that created the view event
page_url The URL of the page where the view event was created
created_at Creation date
email_address The email address of the lead
first_name The first name of the lead if provided
last_name The last name of the lead if provided
business_phone The phone number of the lead if provided
country The country of the lead if provided
company_name The company of the lead if provided
industry The industry that the lead belongs to if provided