OpenAPI Specification
openapi: 3.0.3
info:
title: Brightcove Analytics API Reference Access Tokens Live Analytics API
description: "Reference for the Brightcove Analytics API, used to retrieve analytics data for your accounts. To test API requests, you can use our <a href=\"/getting-started/concepts-testing-tools-brightcove-apis.html\" target=\"_blank\">API Testing Tools</a>.\n\nFor additional in-depth guides to features of the API, see the **[general documentation](/analytics/index.html)**.\n\n **Base URL**: https://analytics.api.brightcove.com"
x-bc-access: public
version: 1.0.0
servers:
- url: https://analytics.api.brightcove.com
variables: {}
tags:
- name: Live Analytics
description: Analytics for Live streams
paths:
/v1/timeseries/accounts/{{account_id}}:
get:
tags:
- Live Analytics
summary: Get Live Analytics time-series
description: A time-series is defined as a an list of timestamp-value pairs representing samples of a variable (metric). The time-series API intends to allow the user to return a time-series for the set of metrics requested in the query.
operationId: GetLiveTimeSeries
security:
- BC_OAuth2:
- video-cloud/analytics/read
parameters:
- $ref: '#/components/parameters/Content-Type'
- $ref: '#/components/parameters/Authorization'
- $ref: '#/components/parameters/Accept-Encoding'
- $ref: '#/components/parameters/account_id'
- $ref: '#/components/parameters/live_dimensions'
- $ref: '#/components/parameters/bucket_limit'
- $ref: '#/components/parameters/bucket_duration'
- $ref: '#/components/parameters/metrics'
- $ref: '#/components/parameters/where'
- $ref: '#/components/parameters/live_from'
- $ref: '#/components/parameters/to'
responses:
'200':
description: '200'
content:
application/json:
schema:
$ref: '#/components/schemas/Get_Time_Series_Response'
'400':
description: 'BAD_REQUEST: The message fields of the response contains information about what caused the error such as invalid value for sort parameter
INVALID_PARAM: The message fields of the response contains information about what invalid params were specified or required params were missing'
'401':
description: 'UNAUTHORIZED: Authentication failed; check to make sure your client credentials are correct'
'404':
description: 'RESOURCE_NOT_FOUND: The api could not find the resource you requested'
'405':
description: 'METHOD_NOT_ALLOWED: This error occurs when the api request is made with an HTTP method other than GET'
'500':
description: 'SERVER_ERROR: Issue in Brightcove system; try again later
PROCESSING: The analytics API may send back this message if it encounters a long running query. Once the query has finished it will be stored in the server’s cache for up to 5 minutes. Therefore we suggest querying the API 4 minutes after receiving this error'
deprecated: false
x-operation-settings:
CollectParameters: false
AllowDynamicQueryParameters: false
AllowDynamicFormParameters: false
IsMultiContentStreaming: false
/v1/events/accounts/{account_id}:
get:
tags:
- Live Analytics
summary: Get Live Analytics event
description: Provides a summary of analytics data collected for a live stream.
operationId: GetLiveEvents
security:
- BC_OAuth2:
- video-cloud/analytics/read
parameters:
- $ref: '#/components/parameters/Content-Type'
- $ref: '#/components/parameters/Authorization'
- $ref: '#/components/parameters/Accept-Encoding'
- $ref: '#/components/parameters/account_id'
- $ref: '#/components/parameters/live_dimensions'
- $ref: '#/components/parameters/metrics'
- $ref: '#/components/parameters/live_where'
responses:
'200':
description: '200'
content:
application/json:
schema:
$ref: '#/components/schemas/Get_Events_Response'
'400':
description: 'BAD_REQUEST: The message fields of the response contains information about what caused the error such as invalid value for sort parameter
INVALID_PARAM: The message fields of the response contains information about what invalid params were specified or required params were missing'
'401':
description: 'UNAUTHORIZED: Authentication failed; check to make sure your client credentials are correct'
'404':
description: 'RESOURCE_NOT_FOUND: The api could not find the resource you requested'
'405':
description: 'METHOD_NOT_ALLOWED: This error occurs when the api request is made with an HTTP method other than GET'
'500':
description: 'SERVER_ERROR: Issue in Brightcove system; try again later
PROCESSING: The analytics API may send back this message if it encounters a long running query. Once the query has finished it will be stored in the server’s cache for up to 5 minutes. Therefore we suggest querying the API 4 minutes after receiving this error'
deprecated: false
x-operation-settings:
CollectParameters: false
AllowDynamicQueryParameters: false
AllowDynamicFormParameters: false
IsMultiContentStreaming: false
components:
parameters:
live_from:
name: from
in: query
description: '''Start time for the period covered by the report — epoch time in milliseconds (`1535654206775`) or a date in the format `yyyy-mm-dd` (such as `2013-09-26`)'''
style: form
explode: true
schema:
oneOf:
- type: string
- type: integer
default: 32 days before now
example: 2018-01-01
live_where:
name: where
in: query
description: "One or more filters to limit responses for Live Analytics requests\nAvailable filters:\n - video\n - country\n - device_type"
required: true
style: form
explode: true
schema:
$ref: '#/components/schemas/live_where'
metrics:
name: metrics
in: query
description: "Data metrics to return for live analytics requests:\n\n - `video_impression` - the number of video impressions\n - `video_view` - the number of video views\n - `video_seconds_viewed` - seconds of video viewed\n - `alive_ss_ad_start` - SSAI ad starts\n - `fingerprint_count` - \"fingerprint\" (user) count\n - `ccu` - concurrent viewers"
required: true
style: form
explode: true
schema:
type: string
enum:
- video_impression
- video_view
- video_seconds_viewed
- alive_ss_ad_start
- fingerprint_count
- ccu
example: video_view,alive_ss_ad_start,ccu
account_id:
name: account_id
in: path
description: a Video Cloud account ID
required: true
style: simple
explode: false
schema:
type: string
to:
name: to
in: query
description: End time for the period covered by the report — `now` or epoch time in milliseconds (`1535654206775`) or a date in the format `yyyy-mm-dd` (such as `2013-09-26`)
style: form
explode: true
schema:
oneOf:
- type: string
- type: integer
default: now
example: '2018-09-01'
Authorization:
name: Authorization
in: header
description: 'Authorization: Bearer access_token (see Getting Access Tokens)'
required: true
style: simple
explode: false
schema:
type: string
live_dimensions:
name: dimensions
in: query
description: "One or more dimensions to report on for Live Analytics requests\nDimensions:\n - video\n - video, country\n - video, device_type"
required: true
style: form
explode: true
schema:
$ref: '#/components/schemas/LiveDimensions'
where:
name: where
in: query
description: one or more 'dimension==value' pairs to filter the results; for live, the only available filters are `country`, `device-type`, and `video`. This is a filter in which the options areL where in the world, in which device or which part of the video. In this case, the property is called where as if to use some DSL that mimics the SQL syntax, and that is why it is called where
required: true
style: form
explode: true
schema:
$ref: '#/components/schemas/live_where'
bucket_limit:
name: bucket_limit
in: query
description: '''Max number of points to be returned for a time-series'''
required: false
example: 10
style: form
explode: true
schema:
type: integer
bucket_duration:
name: bucket_duration
in: query
description: '''Intervals duration in the form of an integer plus `m` (minutes), `h` (hours), or `d` (days)'''
example: 5m
required: false
style: form
explode: true
schema:
type: string
Content-Type:
name: Content-Type
in: header
description: 'Content-Type: application/json'
required: true
style: simple
explode: false
schema:
type: string
Accept-Encoding:
name: Accept-Encoding
in: header
description: 'Accept-Encoding: gzip (optional)'
required: true
style: simple
explode: false
schema:
type: string
schemas:
LiveDimensions:
enum:
- video
- video,country
- video, device_type
Get_Events_Response:
title: Get Events Response
type: object
description: Get live events success response
example:
data:
- dimensions:
country: US
totals:
live_unique_viewers: 1267
video_seconds_viewed: 126755
alive_ss_ad_start: 1274
- dimensions:
country: GB
totals:
live_unique_viewers: 2267
video_seconds_viewed: 136005
alive_ss_ad_start: 1024
properties:
data:
type: array
description: array containing metrics per dimension(s)
items:
type: object
description: object containing `dimensions` and `totals` objects
properties:
dimensions:
type: object
description: Object containing dimension/value that the associated metrics are for
totals:
type: object
description: Object containing metric/value pairs for the associated dimensions
Get_Time_Series_Response:
title: Get Time-Series Response
type: object
description: Get Live time-series success response
example:
video_impression:
data:
- dimensions:
video: '6063969160001'
account: '57838016001'
points:
- timestamp: 1564075800000
value: 11.0
- timestamp: 1564077600000
value: 3.0
video_view:
data:
- dimensions:
video: '6063969160001'
account: '57838016001'
points:
- timestamp: 1564075800000
value: 11.0
- timestamp: 1564077600000
value: 1.0
video_seconds_viewed:
data:
- dimensions:
video: '6063969160001'
account: '57838016001'
points:
- timestamp: 1564075800000
value: 3185.0
- timestamp: 1564077600000
value: 514.0
alive_ss_ad_start: {}
fingerprint_count:
data:
- dimensions:
video: '6063969160001'
account: '57838016001'
points:
- timestamp: 1564075800000
value: 9.0
- timestamp: 1564077600000
value: 6.0
- timestamp: 1564079400000
value: 1.0
ccu:
data:
- dimensions:
video: '6063969160001'
account: '57838016001'
points:
- timestamp: 1564075800000
value: 9.0
- timestamp: 1564077600000
value: 6.0
- timestamp: 1564079400000
value: 1.0
properties:
interval:
type: array
description: array containing the start and end points for the interval in the units specified by the `bucket_duration` parameter
items:
type: integer
dimensions:
type: object
description: A set of dimension/value pairs corresponding to the dimensions specified in the `dimensions` parameter
points:
type: array
description: An array of objects containing metrics for the points in the time-series
items:
type: object
description: An object containing the `timestamp` value (in the units specified in the `bucket_duration` parameter) and values of the metrics (specified in the `metrics` parameter) at the timestamp
live_where:
title: Live where
enum:
- country
- device_type
- video
type: string
example: video==6049313942001,6049313942002
x-enum-elements:
- name: country
description: ''
- name: device_type
description: ''
- name: video
description: ''
securitySchemes:
BC_OAuth2:
type: oauth2
description: Brightcove OAuth API. See the [support documentation](/oauth/index.html) or [Getting Access Tokens](/oauth/code-samples/oauth-api-sample-get-access-token.html) to learn more
flows:
clientCredentials:
tokenUrl: https://oauth.brightcove.com/v4/access_token
scopes:
video-cloud/analytics/read: Read analytics data
video-cloud/video/read: Read video data
x-bc-implicit-head: true
x-bc-implicit-options: true
x-bc-upstream: https://backend_server