Skip Navigation

Warpwire Hotspot Analytics API

Warpwire provides highly granular user interaction reporting, which allows administrators to determine total playtime, segments of the videos or audio file watched, segments that are skipped, or segments that are re-played. This data is collectively referred to as hotspot analytics. It is recorded for every authenticated user for every media asset and provides a very detailed perspective of user interactions.

In addition to individual asset analytic information, Warpwire also provides a higher-level view of the same data, but in a more concise format. This format provides the total duration of playtime, the percentage of the video completed, the first and last access times for the video, and a true/false option indicating whether the user has viewed 95% or more of the video.

Warpwire streamlines the collection and display of this hotspot analytic data; it is all accessible via the Warpwire API.

General Notes

Authentication and authorization – Warpwire requires that all API calls be made over HTTPS, have a valid user authentication token, and follow the conventions as outlined in the Warpwire Data API. Access tokens can be for an individual user session, permanent service accounts, or OAUTH-2 sessions. Authentication is beyond the scope of this document and the reader is encouraged to examine the Warpwire developer documentation or contact Warpwire support for additional information regarding authentication.

API Endpoints – Unless otherwise specified, all API calls share the same Warpwire API endpoint. Please be aware that if you have multiple Warpwire sites, you should verify that you are using the correct Warpwire domain as the API endpoint, as each Warpwire site has a different API endpoint. Usually API endpoints follow the convention:

https://[WARPWIRE_DOMAIN]/api/

Formats – Most hotspot analytic API calls return data either in Javascript Object Notation (JSON), following RFC 7159, or in Comma Separated Value (CSV) format. The default format for all API calls is JSON. Dates should all be specified in ISO-8601 format to avoid ambiguity. However, Warpwire does accept dates is most formats, but will default to UTC as the time zone unless otherwise specified.

Error Messages – Warpwire utilizes the HTTP Response Code field to designate an error message. Error messages are given HTTP response codes 400-499 and fatal errors are designated with HTTP response codes 500-599. Additionally, a JSON-formatted error block will contain the corresponding HTTP response code along with a human readable error message.

Hotspot Analytics API: For all assets or within a specific Media Library

GET Request:

/api/usage/activity/code/<MEDIA_LIBRARY_CODE>/

Parameter Name Description
start (optional) Return analytics records that have a creation date of at least the specified value. If no value is specified, it is assumed to be two years from the current date. It is recommended that the date value be given as a ISO-8601 date time in UTC.
end (optional) Return analytics records that have a creation date prior to the specified value. If no value is specified, it is assumed to be the current date. It is recommended that the date value be given as a ISO-8601 date time in UTC.
format (optional) The output format that response data should be returned. By default all data is returned in JSON format, but if the parameter "csv" is provided the response data will be in CSV format with a content disposition header as an attachment.

Please note:

  • The Media Library code can be provided as the full URL string including the domain name and path information, only the path information, or the direct asset code. If you use the domain and/or path approach, you must ensure that the Media Library code is URL encoded (following the RFC 3986 format).
  • When a Media Library code of "all" is provided, the output will be for all Media Libraries in Warpwire that fall within the defined the start and end parameters. You must have Warpwire site-wide admin access to issue the "all" command, otherwise an error will be returned.
  • The current time duration between the start and end parameter must not exceed two-calendar years (730 days) as this will return an error.
  • This API call is valid for assets that are in video or audio format, any other asset type will result in an error or will be skipped.
  • When using the “all” Media Library code, all assets will be aggregated into a single view. Therefore, the URL parameter and Media Library title may not correspond to the actual result. For additional granularity, it is recommended that you specify a particular Media Library code.
  • You must be the owner of the Media Library or be a Warpwire institutional admin to access the hotspot analytics data or a forbidden error will be returned.

Example Response:

HTTP/1.1 200 OK 
Content-Type: application/json
{
  "AF559DB7F8854A30803BB2DAE8BCF734":{
    "title":"Big Buck Bunny", 
    "duration":"1878", 
    "viewers":{
      "1622":{
        "watched":"00:21:27", 
        "percentage":69,
        "completed":false, 
        "start":"2017-08-23T13:46:34+00:00", "end":"2017-08-23T14:08:01+00:00", "firstName":"Michael", 
        "lastName":"Roberts"
      }, 
      "7326":{
        "watched":"00:25:25", 
        "percentage":81,
        "completed":false, "start":"2017-08-24T14:45:42+00:00", "end":"2017-08-24T15:11:07+00:00", "firstName":"Kathy", 
        "lastName":"Jacobs"
      }, 
      "7116":{
        "watched":"00:00:05", 
        "percentage":0,
        "completed":false, "start":"2017-08-24T13:38:49+00:00", "end":"2017-08-24T13:38:54+00:00", "firstName":"Jackie", 
        "lastName":"Nguyen"
      },
    },
    "creation":"2017-08-23T13:39:33+00:00", 
    "url":"https:\/\/sample.warpwire.com\/w\/zk3ADA\/", "library":"2017 - Sample Videos"
  },
  "139159B2C8924D998FA0D7E9570C52EB":{
    "title":"NASA Space Adventures", 
    "duration":"1906",
    "viewers":{
      "1586":{
        "watched":"00:00:02", 
        "percentage":0,
        "completed":false, "start":"2017-08-24T14:18:25+00:00", "end":"2017-08-24T14:18:27+00:00", "firstName":"Charles",
        "lastName":"Lowe" 
       },
    "creation":"2017-08-23T13:41:44+00:00", 
    "url":"https:\/\/sample.warpwire.com\/w\/FE1CAA\/", "library":"NASA Education Series"
    }
  }
}

The response JSON object is a dictionary keyed by the Universally Unique Identifier (UUID) of each asset within Warpwire. The UUID is consistent across Media Libraries and will not change even if the information regarding the asset is modified. Each media asset object contains a viewer object composed of individual user objects. The viewer object contains a list of user objects keyed by the unique identifier for each user.

Responses:

Parameter Name Description
{key} Universally unique identifier (UUID) of the Warpwire asset. This identifier is consistent across all Media Libraries within Warpwire.
{key}.title The title of the media asset within Warpwire. An asset can be contained in multiple Media Libraries and its title may differ based on this Media Library context.
{key}.duration The media asset’s duration, in total number of seconds. This value is always expressed as an integer, and is rounded up.
{key}.creation The date the asset was added to the Media Library expressed in ISO-8601 date time format.
{key}.url The full URL to access the individual media asset.
{key}.library The name of the Media Library which contains the asset.
{key}.viewers A data object that contains information regarding the unique aggregated viewing session of each unique user who watched the asset within the specified {key} value.
firstName If available, the first name of the user who viewed the asset.
lastName If available, the last name of the user who viewed the asset.
percentage The total amount of the asset that the user watched as defined by: % total = unique time of segment watched / total duration of the asset
completed A Boolean value that returns true when the user has watched 95% or more of a specific asset.
watched The total number of unique seconds that a user has viewed an asset. If a user repeats a section of an asset, only one viewing instance is returned.
start The date and time that a user first accessed the media asset expressed in ISO-8601 date time format.
end The date and time that a user last accessed the media asset expressed in ISO-8601 date time format.

Recommended usage:

This API call is recommended when detailed programmatic access to the viewing history of all assets within Warpwire or within a specific Media Library is desired. This report contains aggregate information that makes it easy to assess whether an individual has watched a media asset or the total percentage of the asset viewed. This API call lacks detailed specificity regarding a unique asset and is only recommended when seeking data in an aggregate fashion across a large number of assets. This call is highly recommended when providing an end user reporting interface.

Hotspot Analytics API: For a single asset

GET Request:

/api/usage/hotspot/code/<ASSET_CODE>/

Parameter Name Description
start (optional) Return analytics records that have a creation date of at least the specified value. If no value is specified, it is assumed to be two years from the current date. It is recommended that the date value be given as a ISO-8601 date time in UTC.
end (optional) Return analytics records that have a creation date prior to the specified value. If no value is specified, it is assumed to be the current date. It is recommended that the date value be given as a ISO-8601 date time in UTC.
format (optional) The output format that response data should be returned. By default all data is returned in JSON format, but if the parameter "csv" is provided the response data will be in CSV format with a content disposition header as an attachment.

Please Note:

  • The asset code can be provided as the full URL string including the domain name and path information, only the path information, or the direct asset code. If you use the domain and/or path approach, you must ensure that the asset code is URL encoded (following the RFC 3986 format).
  • The current time duration between the start and end parameter must not exceed 2 calendar years (730 days) as this will return an error.
  • This API call is valid for assets that are in video or audio format, any other asset type will result in an error.
  • You must be the owner of the asset, have Media Library administrator privileges, or be a Warpwire site-wide admin to access the hotspot analytics data.

Example Response:

HTTP/1.1 200 OK 
Content-Type: application/json
{
  "1622":{
    "properties":{ 
    "firstName":"Michael", 
    "lastName":"Dent", 
    "uniqueId":"md92", 
    "percentage":0.99
    }, 
    "list":[{
      "s":0,
      "startTime":0, 
      "e":98.82, 
      "endTime":1762
    }]
  }, 
  "7588":{
    "properties":{
      "firstName":"Anna", 
      "lastName":"Yuen", 
      "uniqueId":"ay2", 
      "percentage":0.07
    }, 
    "list":[{
      "s":0,
      "startTime":0, 
      "e":0.56, 
      "endTime":10
    }]
  },
  "duration":1783
}

The response JSON object is a dictionary keyed by the unique id of each user who viewed the asset. The user unique identifier is consistent across Media Libraries and will not change even if the user’s information changes between sessions. Each user object contains both a properties and list object. The properties object contains information such as the user’s name, institutional unique identifier (if the information is available and the requestor has sufficient access privileges), and the total percentage of the asset that the user watched. The list object contains individual entries for each time the user watched the video.

Responses:

Parameter Name Description
{key} Universally unique identifier (UUID) of the Warpwire asset. This identifier is consistent across all Media Libraries within Warpwire.
{key}.properties A data object that contains information about the user as designated by the {key} value
firstName If available, the first name of the user who viewed the asset.
lastName If available, the last name of the user who viewed the asset.
uniqueId If available, the organization’s internal identifier for the specified user
percentage The total amount of the asset that the user watched as defined by: % total = unique time of segment watched / total duration of the asset
{key}.list Individual segments representing the user viewing of the asset
s See time computation below. The starting position within the asset that the user starts watching the media asset.
e See time computation below. The ending position within the asset that the user stops watching the media asset.
Time Computation This value is represented as a fractional unit of the total asset duration expressed in percentage of the total. Hotspot Analytics API Equation
startTime The number of seconds that have elapsed since zero where the user first begins watching a unique contiguous section of the asset.
endTime The number of seconds that have elapsed since zero where the user stops watching a unique contiguous section of the asset.
duration The total number of seconds of the asset.

Recommended Usage:

This API call is recommended when detailed programmatic access to the viewing history of a specific asset within a specific Media Library within Warpwire is desired. It is not recommended for aggregate reporting or providing information for more than a small subset of objects.

View Developer APIs page