openapi: 3.0.0
x-bc-implicit-head: true
x-bc-implicit-options: true
x-bc-upstream: 'http://backend_server'
info:
  title: Data Collection API Reference
  description: |-
    Reference for the Brightcove Data Collection API, used to send analytics
    data to the Brightcove analytics system.

    For additional in-depth guides to features of the API, see the **[general documentation](/cms/code-samples/index.html)**.

    **Base URL**: http://metrics.brightcove.com/v2
  version: 2.0.0
servers:
  - url: 'http://metrics.brightcove.com/v2'
    variables: {}
paths:
  /tracker:
    get:
      tags:
        - Events
      summary: Send Event
      description: 'Send event information to the data collector for Brightcove Analytics'
      operationId: SendEvent
      parameters:
        - name: account
          in: query
          description: Account ID **for all requests**
          required: true
          style: form
          explode: true
          schema:
            type: string
        - name: domain
          in: query
          description: domain **for all requests**
          required: true
          style: form
          explode: true
          schema:
            enum:
              - videocloud
            type: string
            example: videocloud
        - name: event
          in: query
          description: The event type **for all requests**
          required: true
          style: form
          explode: true
          schema:
            $ref: '#/components/schemas/Event'
        - name: session
          in: query
          description: >-
            A unique session identifier **for all requests** - see the [Data Collection API Overview](/data-collection/overview-data-collection-api-v2.html#minimal) for more information
          required: true
          style: form
          explode: true
          schema:
            $ref: '#/components/schemas/Session'
        - name: device_os
          in: query
          description: >-
            Override to specify the OS of the device that originated the event
            in cases where the User Agent is unreliable (ignored unless both
            device os and device type are included or if the value submitted is
            not in the list of values shown here. *Not typically included*)
            **for all requests**
          style: form
          explode: true
          schema:
            type: string
        - name: device_manufacturer
          in: query
          description: >-
            Override to specify the manufacturer of the device that originated
            the event in cases where the User Agent is unreliable. *Not
            typically included*) **for all requests**
          style: form
          explode: true
          schema:
            type: string
        - name: device_os_version
          in: query
          description: >-
            The version of os being used by the device. When not specified, this
            will be calculated by parsing the user agent string for the tracking
            request. *Not typically included*) **for all requests**
          style: form
          explode: true
          schema:
            type: string
        - name: device_type
          in: query
          description: >-
            Override to specify the type of the device that originated the event
            in cases where the User Agent is unreliable (ignored unless both
            device os and device type are included or if the value submitted is
            not in the list of values shown here. *Not typically included*)
            **for all requests**
          style: form
          explode: true
          schema:
            type: string
            enum:
              - mobile
              - tablet
              - tv
              - desktop
              - other
        - name: catalog_url
          in: query
          description: >-
            The destination url associated with the `catalog_request` event
            **for `catalog_request` and `catalog_response` event requests**
          style: form
          explode: true
          schema:
            type: string
        - name: response_time_ms
          in: query
          description: >-
            The time, in milliseconds, between the catalog_request event and the
            catalog_response event **for `catalog_request` and
            `catalog_response` event requests**
          style: form
          explode: true
          schema:
            type: integer
            format: int32
        - name: error_code
          in: query
          description: >-
            A platform specific error code associated with the event **for
            `error` event requests**
          style: form
          explode: true
          schema:
            type: integer
            format: int32
        - name: video
          in: query
          description: >-
            The video id **for `video_impression`, `video_view` and `
            `video_engagement`` event requests**
          style: form
          explode: true
          schema:
            type: string
        - name: video_name
          in: query
          description: >-
            The video name **for `video_impression`, `video_view` and `
            `video_engagement`` event requests**
          style: form
          explode: true
          schema:
            type: string
        - name: start_time_ms
          in: query
          description: >-
            The time, in milliseconds, between initiation of playback and the
            first frame of the video being rendered. This can be different
            depending on the experience, for instance, if there are no pre-roll
            ads configured, this measurement is the time between the
            play_request and video_view events. If there is a preroll ad, the
            time between ad_mode_begin and ad_mode_complete should not be
            included **for `video_view` event requests**
          style: form
          explode: true
          schema:
            type: number
        - name: range
          in: query
          description: >-
            The range of the video video viewed for video_engagement events in
            the format StartSecond..EndSecond - range can be left out of an
            engagement event to show that during the period covered by the
            event, there was no viewing activity. (for example, when there is
            only re-buffering activity) **for `video_engagement` event
            requests**
          style: form
          explode: true
          schema:
            type: string
        - name: rendition_url
          in: query
          description: >-
            The url to the most recently selected rendition. For example, for an
            HLS stream this would be the url to the most recently selected
            variant **for `video_engagement` event requests**
          style: form
          explode: true
          schema:
            type: string
        - name: rendition_indicated_bps
          in: query
          description: >-
            The indicated bitrate, in bits per second, of the most recently
            selected rendition **for `video_engagement` event requests**
          style: form
          explode: true
          schema:
            type: string
        - name: rendition_mime_type
          in: query
          description: >-
            The mime type of the most recently selected rendition **for
            `video_engagement` event requests**
          style: form
          explode: true
          schema:
            type: string
        - name: rendition_height
          in: query
          description: >-
            The encoded height of the video rendition in pixels **for
            `video_engagement` event requests**
          style: form
          explode: true
          schema:
            type: string
        - name: rendition_width
          in: query
          description: >-
            The encoded width of the video rendition in pixels **for
            `video_engagement` event requests**
          style: form
          explode: true
          schema:
            type: string
        - name: rebuffering_seconds
          in: query
          description: >-
            The number of seconds the user spent waiting for video to playback
            due to un-requested delay during the engagement period **for
            `video_engagement` event requests**
          style: form
          explode: true
          schema:
            type: number
        - name: rebuffering_count
          in: query
          description: >-
            The number of times playback stopped due to re-buffering during the
            represented engagement period delay during the engagement period
            **for `video_engagement` event requests**
          style: form
          explode: true
          schema:
            type: integer
            format: int32
        - name: forward_buffer_seconds
          in: query
          description: >-
            The number of seconds of video currently residing in the forward
            buffer **for `video_engagement` event requests**
          style: form
          explode: true
          schema:
            type: number
        - name: measured_bps
          in: query
          description: >-
            The ratio of the number of bits included in the most recently
            downloaded segment to the time spend downloading that segment, in
            bits per second **for `video_engagement` event requests**
          style: form
          explode: true
          schema:
            type: number
        - name: player_width
          in: query
          description: >-
            The current pixel width of the player at the end of the engagement
            range **for `video_engagement` event requests**
          style: form
          explode: true
          schema:
            type: number
        - name: player_height
          in: query
          description: >-
            The current pixel height of the player at the end of the engagement
            range **for `video_engagement` event requests**
          style: form
          explode: true
          schema:
            type: number
        - name: dropped_frames
          in: query
          description: >-
            The number of dropped frames duriung the engagement range **for
            `video_engagement` event requests**
          style: form
          explode: true
          schema:
            type: integer
            format: int32
        - name: video_duration
          in: query
          description: >-
            The duration of the video in seconds **for `video_engagement` event
            requests**
          style: form
          explode: true
          schema:
            type: integer
            format: int32
        - name: video_seconds_viewed
          in: query
          description: >-
            The count of watched seconds since the last update for
            video_engagement events **for `video_engagement` event requests**
          style: form
          explode: true
          schema:
            type: number
      responses:
        '200':
          description: ''
        '400':
          description: >-
            BAD_REQUEST: The message fields of the response contains information
            about what caused the error such as invalid value for sort
            parameter

            UNSUPPORTED_FIELD_COMBINATION_ERROR: The message fields of the
            response contains information about what invalid fields were
            specifed
        '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 '
      deprecated: false
      security: []
      x-operation-settings:
        CollectParameters: false
        AllowDynamicQueryParameters: false
        AllowDynamicFormParameters: false
        IsMultiContentStreaming: false
components:
  schemas:
    'UrlParameters:AllRequests':
      title: 'URL Parameters: All Requests'
      required:
        - account
        - domain
        - event
      type: object
      properties:
        account:
          type: string
          description: account id
        domain:
          type: string
          description: always equal to videocloud
        event:
          type: string
          description: the event type
          enum:
            - player_load
            - catalog_request
            - catalog_response
            - play_request
            - ad_mode_begin
            - ad_mode_complete
            - video_impression
            - video_view
            - video_engagement
            - error
        device_os:
          type: string
          description: >-
            Override to specify the OS of the device that originated the event
            in cases where the User Agent is unreliable (ignored unless both
            device os and device type are included or if the value submitted is
            not in the list of values shown here. Not typically included)
          enum:
            - android
            - bada
            - ios
            - linux
            - mac
            - tv
            - os_x
            - rim
            - sybian
            - windows
            - other
        device_manufacturer:
          type: string
          description: >-
            Override to specify the manufacturer of the device that originated
            the event in cases where the User Agent is unreliable (Not typically
            included)
          enum:
            - android
            - bada
            - ios
            - linux
            - mac
            - tv
            - os_x
            - rim
            - sybian
            - windows
            - other
        device_os_version:
          type: string
          description: >-
            The version of os being used by the device. When not specified, this
            will be calculated by parsing the user agent string for the tracking
            request
        device_type:
          type: string
          description: >-
            Override to specify the type of the device that originated the event
            in cases where the User Agent is unreliable (ignored unless both
            device os and device type are included or if the value submitted is
            not in the list of values shown here. Not typically included)
          enum:
            - mobile
            - tablet
            - tv
            - desktop
            - other
        destination:
          type: string
          description: URI that originated the event
        source:
          type: string
          description: URI that sent the end-user to the destination URI
        time:
          type: number
          description: the timestamp for the event in epoch time (milliseconds)
        country:
          type: string
          description: >-
            ISO-3166 (alpha 2) region cISO-3166 (alpha 2) region code (override
            in case the system can not detect geographic information from the IP
            address) Not typically included
        country_name:
          type: string
          description: >-
            Human readable country name (override in case the system can not
            detect geographic information from the IP address) Not typically
            included
        region:
          type: string
          description: >-
            ISO-3166 (alpha 2) region code (override in case the system can not
            detect geographic information from the IP address) Not typically
            included
        region_name:
          type: string
          description: >-
            Human readable region name (override in case the system can not
            detect geographic information from the IP address) Not typically
            included
        city:
          type: string
          description: City name Not typically included
        user:
          type: string
          description: >-
            A unique user identifier - if not provided or blank, Video Cloud
            uses the fallback method of using the Source IP address + the
            User-Agent String as the unique identifier; Note that Brightcove
            uses this information only to calculate unique users. The user data
            itself cannot retrieved via the API or Analytics module
    'Url parameters: `catalogRequest` events':
      title: 'URL Parameters: `catalog_request` Events'
      type: object
      properties:
        catalog_url:
          type: string
          description: The destination url associated with the catalog_request event
    'Url parameters: `catalogResponse` events':
      title: 'URL Parameters: `catalog_response` Events'
      type: object
      properties:
        catalog_url:
          type: string
          description: >-
            The destination url associated with the catalog_request event that
            initiated this response
        response_time_ms:
          type: number
          description: >-
            The time, in milliseconds, between the catalog_request event and the
            catalog_response event
    'UrlParameters:`error`Events':
      title: 'URL Parameters: `error` Events'
      type: object
      properties:
        error_code:
          type: number
          description: A platform specific error code associated with the event
    'Url parameters: `videoImpression` events':
      title: 'URL Parameters: `video_impression` Events'
      type: object
      properties:
        video:
          type: string
          description: the video id
        video_name:
          type: string
          description: the video name
    'Url parameters: `videoView` events':
      title: 'URL Parameters: `video_view` Events'
      type: object
      properties:
        video:
          type: string
          description: the video id
        video_name:
          type: string
          description: the video name
        start_time_ms:
          type: string
          description: >-
            The time, in milliseconds, between initiation of playback and the
            first frame of the video being rendered. This can be different
            depending on the experience, for instance, if there are no pre-roll
            ads configured, this measurement is the time between the
            play_request and video_view events. If there is a preroll ad, the
            time between ad_mode_begin and ad_mode_complete should not be
            included
    'Url parameters: `videoEngagement` events':
      title: 'URL Parameters: `video_engagement` Events'
      type: object
      properties:
        video:
          type: string
          description: the video id
        video_name:
          type: string
          description: the video name
        range:
          type: string
          description: >-
            the range of the video video viewed for video_engagement events in
            the format StartSecond..EndSecond - range can be left out of an
            engagement event to show that during the period covered by the
            event, there was no viewing activity. (for example, when there is
            only re-buffering activity)
        rendition_url:
          type: string
          description: >-
            The url to the most recently selected rendition. For example, for an
            HLS stream this would be the url to the most recently selected
            variant
        rendition_indicated_bps:
          type: string
          description: >-
            The indicated bitrate, in bits per second, of the most recently
            selected rendition
        rendition_mime_type:
          type: string
          description: The mime type of the most recently selected rendition
        rendition_height:
          type: string
          description: The encoded height of the video rendition in pixels
        rendition_width:
          type: string
          description: The encoded width of the video rendition in pixels
        rebuffering_seconds:
          type: string
          description: >-
            The number of seconds the user spent waiting for video to playback
            due to un-requested delay during the engagement period
        rebuffering_count:
          type: string
          description: >-
            The number of times playback stopped due to re-buffering during the
            represented engagement period delay during the engagement period
        forward_buffer_seconds:
          type: string
          description: >-
            The number of seconds of video currently residing in the forward
            buffer
        measured_bps:
          type: string
          description: >-
            The ratio of the number of bits included in the most recently
            downloaded segment to the time spend downloading that segment, in
            bits per second
        player_width:
          type: string
          description: >-
            The current pixel width of the player at the end of the engagement
            range
        player_height:
          type: string
          description: >-
            The current pixel height of the player at the end of the engagement
            range
        dropped_frames:
          type: string
          description: dropped_frames
        video_duration:
          type: number
          description: the duration of the video in seconds
        video_seconds_viewed:
          type: number
          description: >-
            count of watched seconds since the last update for video_engagement
            events
    Event:
      title: event
      enum:
        - catalog_request
        - catalog_response
        - error
        - video_impression
        - video_view
        - video_engagement
      type: string
      example: catalog_request
      x-enum-elements:
        - name: catalog_request
          description: ''
        - name: catalog_response
          description: ''
        - name: error
          description: ''
        - name: video_impression
          description: ''
        - name: video_view
          description: ''
        - name: video_engagement
          description: ''
    Session:
      title: session
      type: string
      description: A GUID to identify the session
      example: 733b52a5-b139-4718-ad21-aec5bd8d2604
