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>/

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

{
  "1221": {
    "properties": {
      "firstName": "support@warpwire.net",
      "lastName": "Support",
      "userId": "1221",
      "uniqueId": "support@warpwire.net",
      "anonymous": false,
      "hasWatched": true,
      "lastWatched": "2021-02-03T20:16:02+00:00",
      "percentage": 1,
      "lastWatchedUtc": "2021-02-03T20:16:02+00:00"
    },
    "list": [
      {
        "s": 0.02,
        "startTime": 0,
        "e": 100,
        "endTime": 128
      }
    ]
  },
  "1463": {
    "properties": {
      "firstName": "Thuy",
      "lastName": "",
      "userId": "1463",
      "uniqueId": "thuy@warpwire.net",
      "anonymous": false,
      "hasWatched": true,
      "lastWatched": "2020-11-16T19:56:02+00:00",
      "percentage": 0.71,
      "lastWatchedUtc": "2020-11-16T19:56:02+00:00"
    },
    "list": [
      {
        "s": 4.75,
        "startTime": 6,
        "e": 9.44,
        "endTime": 13
      },
      {
        "s": 15.38,
        "startTime": 19,
        "e": 20.07,
        "endTime": 26
      },
      {
        "s": 26.31,
        "startTime": 33,
        "e": 31,
        "endTime": 40
      },
      {
        "s": 36.1,
        "startTime": 46,
        "e": 68.95,
        "endTime": 89
      },
      {
        "s": 75.7,
        "startTime": 96,
        "e": 100,
        "endTime": 128
      }
    ]
  },
  "duration": 128,
  "totalSecondsViewed": "381.000"
}

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:

Hotspot Analytics API: For a single asset

GET Request:

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

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

{
  "340438090663416E84FCE9AADB8E45DB": {
    "title": "Kneading Dough",
    "duration": "35.040000915527344",
    "viewers": {
      "1221": {
        "watched": "00:00:02",
        "percentage": 6,
        "completed": false,
        "start": "2020-11-13T20:57:43+00:00",
        "end": "2020-11-13T20:57:45+00:00",
        "firstName": "support@warpwire.net",
        "lastName": "Support"
      }
    },
    "creation": "2020-11-13T15:54:08-05:00",
    "url": "https://support.warpwire.com/w/9UcAAA/",
    "library": "Food and Cooking 101"
  },
  "68C92A0EBFB94B789EBC4B2A2F8AEF87": {
    "title": "Edinburgh Food Social-HD.mp4 (720p HD).mp4",
    "duration": "128.94000244140625",
    "viewers": {
      "1465": {
        "watched": "00:01:25",
        "percentage": 67,
        "completed": false,
        "start": "2020-11-16T20:07:51+00:00",
        "end": "2020-11-13T07:19:47+00:00",
        "firstName": "Saul",
        "lastName": ""
      },
      "1463": {
        "watched": "00:01:30",
        "percentage": 70,
        "completed": false,
        "start": "2020-11-16T19:54:16+00:00",
        "end": "2020-11-13T01:55:03+00:00",
        "firstName": "Thuy",
        "lastName": ""
      },
      "1221": {
        "watched": "00:02:07",
        "percentage": 100,
        "completed": true,
        "start": "2020-11-16T19:45:36+00:00",
        "end": "2020-11-16T18:33:17+00:00",
        "firstName": "support@warpwire.net",
        "lastName": "Support"
      }
    },
    "creation": "2020-11-13T16:27:11-05:00",
    "url": "https://support.warpwire.com/w/90cAAA/",
    "library": "Food and Cooking 101"
  }
}

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.
userId	Warpwire ID of the Warpwire user. This identifier is consistent across all Media Libraries within Warpwire.
uniqueId	If available, the organization’s internal identifier for the specified user
anonymous	Is the current user anonymous? The values can include either "true" or "false". If the user is not logged in, then they will be anonymous and the result will always be true.
hasWatched	Has the user watched the video? The values can include either "true" or "false". If the user has watched the video, the result will always be "true".
lastWatched	The time that the user has last watched the video. The time reflected in lastWatched will be the same timezone that is used in the startTime and endTime.
lastWatched UTC	The time that the user has last watched the video. This time will always be in UTC.
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.
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.