Page Contents

    Overview: Dimensions, Fields, and Parameters

    Dimensions are the key data categories for Analytics API data reports. This topic provides an interactive guide to dimensions and the fields that can be returned for them. It also shows which dimensions can be combined in a report, and the fields available for the different combinations.

    Dimensions and fields

    Dimensions are the primary data buckets for analytics. To see full guides to the individual dimensions, click on the dimension name in the list below.

     
     

    Select dimension(s) below to see the fields that can be returned for it. You can also click the Make a Request button to make a sample request and see the results. If you select multiple incompatible dimensions, you will see a message to that effect.

    Input

    Select Dimension(s) to report on:

     
     

    Fields to return:

     
     

    (uses a sample Brightcove account)

    Output

    Earliest from date for this dimension combination:  

     

    Sample API request:

    Response data

      Response will appear here...

    Notes

    1. By default, video_view is the only field returned - other fields will be returned only if they are specified in the value of the fields parameter.
    2. If you specify a field to return that is not supported for the dimension or dimension combination, an UNSUPPORTED_FIELD_COMBINATION_ERROR error will be returned.
    3. The bytes_delivered field includes all data delivered by Video Cloud to clients, including video data, images, text tracks and other assets, as well as the player code itself. Some of this data is obtained from CDNs, and may not be available for up to 3 days.
    4. In addition to the fields shown for the video dimension, you can also return video.custom_fields.{field_name}

    Example request

    A typical use case for getting a report on multiple dimensions: you want a breakdown of video views between desktop and mobile devices, and also want to know how many of the mobile device views were on iOS versus Android devices, and how many of the desktop views were on Macs versus Windows machines. Currently there is no standard report in the Studio Analytics Module that provides this information, but you can obtain it via this Analytics API call:

      https://analytics.api.brightcove.com/v1/data?accounts=57838016001&dimensions=video,device_type,device_os&from=2014-01-01&to=2014-04-01&fields=video_view

    (In this case we are requesting video views for the period from January 1 to April 1 in 2014.)

    Example using cURL

    If you want to try out the API using cURL, here are a couple of notes:

    • You will first need to get an access token
    • Since the URL for the request will always include URL parameters, you will need to enclose it in quotation marks (single or double)

    Sample

    Here is a sample cURL command:

      curl -s --header "Authorization: Bearer $ACCESS_TOKEN" \
      "https://analytics.api.brightcove.com/v1/data?accounts={account_id}&dimensions=video&from=2017-04-04&limit=100"

    If you replace $ACCESS_TOKEN with a valid access token, and {account_id} with you account id, this request should work. Note that you can use this sample app to generate an access token.

    Supported dimension combinations

    For quick reference, the table below shows dimension combinations that are supported or not. Note that there are a few cases where more than two dimensions can be used. You can figure these out using the Dimensions and Fields tool above.

    Supported Dimension Combinations
      account browser_type city country date date_hour destination_domain destination_path device_os device_manufacturer device_type live_stream player referrer_domain region search_terms social_platform source_type video
    account n/a    
    browser_type n/a                            
    city   n/a                        
    country   n/a                  
    date n/a  
    date_hour   n/a
    destination_domain       n/a                    
    destination_path         n/a                      
    device_os         n/a              
    device_manufacturer             n/a                  
    device_type             n/a          
    live_stream                   n/a              
    player           n/a      
    referrer_domain                   n/a    
    region               n/a        
    search_terms                       n/a    
    social_platform                             n/a  
    source_type                       n/a
    video               n/a

    URL parameters

    Analytics API reports support the following URL parameters.

    URL Parameters
    Parameter Description Required Values Default
    account The accounts you want to report on yes one or more account ids as a comma-delimited list none
    dimensions The dimension(s) to report on yes one or more dimensions as a comma-delimited list (some combinations are not valid - use the interactive tool here to determine if a combination is valie) none
    where Used to specify filters for reports no {dimension}=={value} - one or more as a semi-colon-delimited list. The value will be one or more values for the primary metric of that dimension. For example: video==video_id, country=country-code, or viewer=viewer_id (in the last case, the form of the viewer_id will vary depending on whether you are capturing and sending some kind of viewer_id yourself or depending on the value generated by the analytics system). none
    limit Number of items to return no positive integer 10
    offset Number of items to skip no positive integer 0
    sort Field to sort items on no any field that is being returned by the request video_view
    fields Fields to return no varies according to the dimension you are reporting on video,video_view
    format Format to return results in no json (default) | csv | xlxs json
    reconciled If included, will limit results to either historical or realtime data. Analytics data is derived from multiple sources: some is sent by the player, but other data is collected from CDNs and the Video Cloud system. In order to deliver analytics as quickly as possible, we start delivering "real-time" data as soon as it is available, and then adjust the analytics later when data from all sources has been collected and processed. The fully processed data is called reconciled no true | false true
    from The beginning of the date range for the request no One of the following:
    • An ISO 8601 date (YYYY-MM-DD)
    • Epoch time in milliseconds (example: 1659641316719 [= Thursday, August 4, 2022 7:28:36.719 PM GMT]). See the Epoch time converter.
    • A string: from=alltime
    • +/- relative dates in days (d), weeks (w), or months (m) - example: from=-6m&to=%2B2w (the period from 6 months ago to 2 weeks after that -- note that the + sign needs to be URI encoded as %2B)

    Only dates within the past 32 days are allowed for engagement endpoints or if reconciled=false.

    -30d
    to The end of the date range for the request no One of the following:
    • An ISO 8601 date (YYYY-MM-DD)
    • Epoch time in milliseconds (example: 1659641316719 [= Thursday, August 4, 2022 7:28:36.719 PM GMT]). See the Epoch time converter.
    • A string: to=now
    • +/- relative dates in days (d), weeks (w), or months (m) - example: from=-6m&to=%2B2w (the period from 6 months ago to 2 weeks after that -- note that the + sign needs to be URI encoded as %2B)

    Only dates within the past 32 days are allowed for engagement endpoints or if reconciled=false.

    now

    Accounts

    The Video Cloud account(s) that you want a report for are specified using the accounts parameter. For example:

      https://analytics.api.brightcove.com/v1/data?accounts={account1_id,account2_id}

    Where filters

    The general syntax for filters is:

    where=dimension1==value1;dimension2==value2

    For example:

    https://analytics.api.brightcove.com/v1?accounts=account_id(s)&dimensions=device_type&where=video==video_id;device_type==tablet

    Commas are treated as logical ORs, and semicolons as logical ANDs. For example, where=video==1234,5678;player==9876 is interpreted as "where video = 1234 OR 5678 AND player = 9876"

    Spaces and special characters

    String values should be URI encoded. You can also escape special characters using a "":

    where=search_terms==boston,%20ma

    You can use any dimension as a filter, but only if that dimension is also included in the dimensions you are requesting.

    Filtering by video properties

    Using the special where=video.q=={property}:{value} filter, you can limit your report to a specific set of videos based on a variety of properties, including:

    • tags
    • reference_id
    • custom_fields [1]
    • {a_specific_custom_field}
    • created_at

    Notes

    [1] The basic syntax is where=video.q==custom_fields:value (matches the value in any custom field) or where=video.q==myfield:value (matches the value in the specific custom field myfield). If you are searching on a specific custom fields, note that you must search on the Internal Name, not the Display Name:

    Internal Name vs Display Name
    Internal Name vs Display Name

    One quick check on whether you are using the right name: the internal name will be all lowercase and contain no spaces.

    Examples

    Here are some example where filters for searching on tags and custom fields:

    Single tag
    where=video.q==tags:foo
    Multiple tags:
    where=video.q==tags:foo,bar
    Custom fields
    where=video.q==custom_fields:foo
    Tags and custom fields
    where=video.q==tags:foo,bar+custom_fields:fish

    Note that the video.q search functionality includes AND, OR and NOT logic as follows:

    • A + (plus) sign before the search term means results must include this term.
    • A - (minus) sign before the search term means results must not include this term.
    • If there is neither a plus or minus sign, results may or may not include this term.

    The following examples illustrate the use of this logic.

    Search Examples
    where Filter Results
    where=video.q==tags:red%20tags:blue%tags:green videos with the tags red OR blue OR green will be returned
    where=video.q==+tags:red%20tags:blue%tags:green returned videos MUST have the tag red AND may have the tags blue OR green
    where=video.q==+tags:red%20tags:blue%-tags:green returned videos MUST have the tag red AND may have the tag blue, but must NOT have the tag green

    For a complete explanation of this query syntax, see Using the CMS API: Search for Videos.

    Summary of filters and allowable values

    The following table shows allowable values for each dimension used as a filter:

    Dimension Filter Allowable Values

    Date ranges

    Date ranges, specified in from and to parameters for all types of reports, can be indicated in different formats:

    • Text values:
      • to=now (available and the default value for all requests)
    • Epoch time values in milliseconds, such as 1377047323000
    • Dates expressed in ISO 8601 standard international date format: YYYY-MM-DDformat, such as 2013-09-12. For dates expressed in this format:
      • Any date range specified will be interpreted in the timezone set for the account
      • The time for the date give will be interpreted as midnight ( 00:00:00) on the date specified in the timezone set for the account
    • Relative dates: you can express either of the to and from values relative to the other one in d (days) or h (hours). 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=2014-12-31

      Note that negative numbers (-2d) are interpreted as "before" (the other value) and positive numbers (48h) are treated as "from" (the other value)

    To generate a report on some dimension like "video" for a single day, set the to and from values to that date:

    ...&dimensions=video&from=2013-11-01&to=2013-11-01

    Limit and offset

    The limit is the number of items to return (default: 10). To return all items, use limit=all. 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.

    Reconciled data

    The reconciled parameter is a boolean. If it is set to true, the results will be limited to reconciled data. If false, results will be limited to realtime (hourly unreconciled) data.

    Geographical reports

    Dimensions for geographical analytics

    • country - As the ISO-3611-1 country code. eg: 'US'
    • region - As the ISO-3611-2 region code. eg: 'US-WA'
    • city - City name. eg: Seattle

    Note: For unknown country or region the API returns "ZZ" as the code (As per ISO-3611-alpha2).

    Fields and Sorting

    Use the fields parameter to specify the fields you want to return. By default, video_view is returned and the field corresponding to the dimension you are reporting on (e.g. destination_domain) are returned. See dimensions and fields for more details.

    Use the sort parameter to specify which metric field is used to sort the returned items; for example: sort=video_view. You can reverse the sort order by negating the sort field: sort= -video_view.

    Calculated fields

    You can add calculated fields to your API requests using the syntax:

    fields=calulated_field_name:expression

    You can use calculated fields to create your own custom fields out of existing metrics, or to rename an existing field.

    The name for the calculated field can be any URI-compatible string. The expression can include regular field names and the following arithmetic operators:

    • + (addition)
    • - (subtraction)
    • * (multiplication)
    • / (division)
    • ^ (exponent)
    • () (parentheses)

    Examples

    fields=avg_seconds_viewed:video_seconds_viewed/video_view,video.name
    fields=avg_incomplete_ads:(ad_mode_begin-ad_mode_complete)/video_view,video.name
    fields=Video%20Views:video_view,video.name

    Sample request

    Sample response (to the request above)

    {
      "item_count": 110,
      "items": [
        {
          "avg_seconds_viewed": 2152.2519913106444,
          "video.name": "Flamingos",
          "video_seconds_viewed": 2972260,
          "video": "4825279519001",
          "video_view": 1381
        },
        {
          "avg_seconds_viewed": 14.016225448334756,
          "video.name": "Tiger",
          "video_seconds_viewed": 16413,
          "video": "4093643993001",
          "video_view": 1171
        },
        {
          "avg_seconds_viewed": 12.06,
          "video.name": "Zebra",
          "video_seconds_viewed": 9045,
          "video": "3851389913001",
          "video_view": 750
        },
        {
          "avg_seconds_viewed": 23.343065693430656,
          "video.name": "Sea-SeaTurtle",
          "video_seconds_viewed": 15990,
          "video": "1754276205001",
          "video_view": 685
        }
      ],
      "summary": {
        "avg_seconds_viewed": 274.27374399301004,
        "video_seconds_viewed": 3139063,
        "video_view": 11445
      }
    }

    Page last updated on 04 Aug 2022