Overview: Audience API

API reference

Also see the API Reference.

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:

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.

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:

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: 200). 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}"

{
"count": 27,
"limit": 25,
"offset": 0,
"result": [
    {
        "created_at": "2016-04-25T18:30:21.651Z",
        "page_url": "https://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": "https://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:

Retrieving leads

To retrieve leads in an account, perform a GET request to the leads resource:

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

{
"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": "https://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": "https://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: