support Contact Support | system status System Status
Page Contents

    Overview: Audience API

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

    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:

    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.

    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

    Page last updated on 19 Mar 2020