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.
GET Request:
/api/usage/activity/code/<MEDIA_LIBRARY_CODE>/
| Parameter Name | Description |
|---|---|
| start (optional) -- deprecated | 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. Please use startTime instead, as this parameter is deprecated. |
| end (optional) -- deprecated | 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. Please use endTime instead, as this parameter is deprecated. |
| startTime (optional) | Return analytics records that have a creation date/time 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. If a time zone is provided, it will ensure that the data is returned in the local timezone. If no time zone is provided, it will use UTC. |
| endTime (optional) | Return analytics records that have a creation date/time 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. If a time zone is provided, it will ensure that the data is returned in the local timezone. If no time zone is provided, it will use 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:
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:
| Parameter Name | Description |
|---|---|
| {key} | Warpwire ID of the Warpwire user. 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.
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:
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. |
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.
