Skip Navigation

Warpwire Reporting API

The Warpwire Reporting API provides a simple interface to retrieve all of the metrics collected by Warpwire. A subset of these metrics are also provided in the Warpwire graphical report interface — this reference guide contains a much more comprehensive view of the available reporting information.

This guide does not require any programming experience, and is designed to be integrated into your existing reporting software. Please note that some of the data may require more advanced statistical manipulation, which is outside the scope of this guide. Additionally, Warpwire may only be able to provide limited support for the use of any APIs.

Reporting API: Requirements

The Warpwire API requires a software package that can make standard basic authenticated HTTP requests. Warpwire API requests require the use of the secure HTTPS protocol via Transport Layer Security (TLS) — please ensure that your software package provides this functionality. The Warpwire Reporting API returns data in JavaScript Object Notation (JSON) format, and requires that any software package used be able to decode these response objects.

Reporting API: Authentication

All API requests require the use of HTTP Basic authentication. You must be able to supply both a username and password to make each request. You may have to contact your system administrator or Warpwire support to have an authorized key added to the authentication list in order to use the Warpwire API. If you receive one of the following errors: HTTP/1.1 401 Unauthorized or HTTP/1.1 403 Forbidden, please check your username and password to make sure that they are valid. Please note that you should be able to make any of these requests via a standard web browser. It is always recommended that you first attempt to access the URL via your browser to ensure that your reporting software can appropriately access the Warpwire Reporting API.

More advanced authentication methods such as the use of OAUTH-based authentication are not covered in this document.

Reporting API: Limiting Reporting Data

Most reporting queries support both a date and limit operator. These operators allow you to specify a specific date range, with granularity to a specific day. The limit operator allows you to further suppress the total number of results that are returned by the API. Please note that results may be automatically limited by the API based on your permission level. In this case, you will need to paginate through the results or further restrict your date range to return the entire dataset.

The date operators are specified as an additional parameter to any API query. To restrict any query to a specific date, simply append a start and end parameter to your query (please see date convention below). For instance, if you were using the following API query to provide a list of basic usage statistics:

https://<API_PATH>/stats/basic/

You would modify the query as follows to restrict the results to a one week period of time:

https://<API_PATH>/stats/basic/?start=20150510&end=20150517

This would provide the basic statistical information from May 10, 2015 through May 17, 2015 (inclusive).

Parameter Name Description
start The start date for the report. This should be a fully qualified date including at least the month and the year. All start parameters begin at midnight of the timezone specified by your administrator.
end The end date for the report. This should be a fully qualified date including at least the month and the year. All end parameters end at 23:59:59 of the timezone specified by your administrator.

If no start date is specified in the API call, this value defaults to 7 days before the present day. If no end date is specified in the API call, this value defaults to the current date/time. The start date must occur before the end date, otherwise an error will be returned from the API. Note that the date range is inclusive — the dates that are specified as both the start and end dates will be included in the results.

Dates may only be specified in the format listed below. Any deviation from this format will result in spurious results. Please note that every API query returns both the start and end dates. You may use this value to validate that your date parameters are correct.

Date Format Description
YYYYMMDD 4 digit year, 2 digit month, followed by a 2 digit day. Any value under the specified length should be zero padded.
YYMMDD 2 digit year, 2 digit month, followed by a 2 digit day. Any value under the specified length should be zero padded.
MONTHYYYY Textual description of the month followed by 4 digit year. For example June2015. If both the start and end dates are the same, then the API will return one month of data starting from the first day of that month to the last second of the last day of that same month. If the start and end dates differ by one month (e.g. start:June2015 and end:July2015) this will return two months of data.

The limit operators are specified as an additional parameter to any API query. To restrict any query to a specific limit, simply append a limit parameter to your query. For instance, if you were using the following API query to provide a list of basic usage statistics:

https://<API_PATH>/stats/basic/

You would modify the query as follows to restrict the number of returned results:

https://<API_PATH>/stats/basic/?limit=50

This would provide the basic statistical information and would only return the first 50 results. By default, all API queries are limited to a set number of records (for example, 10 records) unless you explicitly specify a higher limit. Please note that the API may restrict the number of records returned despite the value manually specified by the limit operator. All limit operator values must be greater than 0.

Reporting API: Reporting Topics

The topics API call provides a list of all possible API calls that may be made to the reporting system. This list may change depending on the permission of the authenticated user. The resource URL looks like this:

https://<API_URL>/api/stats/topics/

This API call does not support any optional parameters such as a date range or limit clause.

An example request for a list of reporting topics in Warpwire is as follows:

curl -u “username:password" https://test.warpwire.com/api/stats/topics/

The following fields are returned in the topics call:

Parameter Name Description Example
id The numeric index for how the topic should be displayed to the user. 4
topic The human readable name of the topic to display to the user. Unique Viewers
url A relative URL to access the specific topic API call. /stats/views/
description An extended description of the topic that explains any additional functionality. a sample description
extendedParams Indicates there are non- standard options that are available to this API call. TRUE
default The default (first) option to show to the user when providing a list of topics. FALSE
canDownload Denotes that a CSV file can be downloaded which includes extended information. TRUE
downloadUrl A fully qualified URL to download the extended information via a CSV file. https://example.warpwire .com/api/stats/views/? download=true&u=1&sig nature=5f4bb9fc37ebdf5 086cb68e43420b&ts=14 428&nonce=657

Reporting API: Basic Statistics

The basic statistic API call provides an aggregate view of all of the statistics information within a time range. This list is only accessible to a user with administrative access to Warpwire. The resource URL looks like this:

https://<API_URL>/api/stats/basic/

This API call supports the following optional parameters:

Field Description Example
start The beginning date range of the report. Refer to the Limiting Reporting Data section above. July2015
end The end date range of the report. Refer to the Limiting Reporting Data section above. December2018

An example request for retrieving basic statistics in Warpwire is as follows:

curl -u "username:password" https://test.warpwire.com/api/stats/basic/

The following fields are returned in the basic statistics call:

Parameter Name Description Example
users Total number of newly created users during the specified time period. 409
files Total number of files created during the specified time period. This includes all file types. 1045
libraries Total number of Media Libraries created during the specified time period. This also includes automatically created Media Libraries. 207
seconds Total number of seconds of content watched by all users during the specified time period. 7299
viewers Total number of unique viewers who viewed media during the specified time period. 24
types [Numeric indexed array] Total number of newly created objects organized by their media type. [{count: 230, type:image}, {count: 2, type:audio}]
sessions [Numeric indexed array] Total number of user browsing sessions specified by their platform and operating system. [{platform: Mac, browser: Safari Mobile, count: 10}, {platform: Windows, browser: Internet Explorer, count: 7}]
start Fully formatted date that indicates the start value used for generating the report. 2014-06-01 00:00:00
end Fully formatted date that indicates the ending value used for generating the report. 2016-06-30 23:59:59

Reporting API: Top Users Statistics

Provides statistics based on the playback usage of all users within the system. This calculates the total number of seconds that a user has viewed content during the specified time period. These statistics are only accessible to users with administrative access to Warpwire. The resource URL looks like this:

https://<API_URL>/api/stats/top/users/

This API call supports the following optional parameters:

Field Description Example
start The beginning date range of the report. Refer to the Limiting Reporting Data section above. July2015
end The end date range of the report. Refer to the Limiting Reporting Data section above. December2018
limit Restrict the number of results to the specified value. 100

An example request for retrieving top user statistics in Warpwire is as follows:

curl -u “username:password" https://test.warpwire.com/api/stats/top/users/? start=July2015&end=Decemeber2016&limit=100

The following fields are returned in the top users call:

Field Description Example
users [Numeric indexed array] Specific information regarding each user (See below). [{id: 3, firstName: Jane, lastName: Doe, email: jane.doe@example.com , watched: 1423, plays: 15}]
users[0].id Unique identifier of the user as specified by an external sign in system. jt410
users[0].firstName First name of the user as specified by an external sign in system. Maria
users[0].lastName Last name of the user as specified by an external sign in system. Browm
users[0].email Email address of the user as specified by an external sign in system (this may be empty). maria.brown@school.edu
users[0].watched Number of seconds that the user has watched content during the specified time period. 1415
users[0].plays Number of unique sessions that the user has viewed videos within the specific time period. 14
start Fully formatted date that indicates the start value used for generating the report. 2014-06-01 00:00:00
end Fully formatted date that indicates the ending value used for generating the report. 2016-06-30 23:59:59

Reporting API: Top Media Statistics

Provides statistics based on the most watched assets within the Warpwire system. This report calculates the total number of seconds that all users have viewed content throughout the specified time period for a specific media element. This report collapses the Media Library space and treats a media asset in several Media Libraries as a single asset. These statistics are only accessible to users with administrative access to Warpwire. The resource URL looks like this:

https://<API_URL>/api/stats/top/media/

This API call supports the following optional parameters:

Field Description Example
start The beginning date range of the report. Refer to the Limiting Reporting Data section above. July2015
end The end date range of the report. Refer to the Limiting Reporting Data section above. December2018
limit Restrict the number of results to the specified value. 100
download Return the results in CSV format to be downloaded to the client. The output is not compressed. CSV Output File

An example request for top media statistics in Warpwire is as follows:

curl -u “username:password" “https://test.warpwire.com/api/stats/top/media/? start=July2015&end=Decemeber2016&limit=100"

The following fields are returned in the top media call:

Parameter Name Description Example
files [Numeric indexed array] Specific information regarding each media asset (See below). [{link:https://example. warpwire.com/w/ DWYAAA/, title:"Neon Song", watched:"2", plays:"1", averageWatched:2, averageSession:2}]
files[0].link URL to access the resource. This attribute should be considered mutable and may change on subsequent calls to this report. https://example.warpwire .com/w/DWYAAA/
files[0].title The name of the media asset. Neon Song
files[0].watched The total number of seconds that the media asset was watched (in seconds). 2
files[0].plays The number of unique instances that the media element was played. A play is defined as starting a media element from the zero position and advancing it at least one time iteration. 2
files[0].averageWatched The average number of seconds that this media asset was viewed. The average is calculated by dividing the number of viewed seconds by the number of unique plays 2
files[0].averageSession The average number of seconds an asset is watched based on viewing sessions only, without considering a unique play. 14
start Fully formatted date that indicates the start value used for generating the report. 2014-06-01 00:00:00
end Fully formatted date that indicates the ending value used for generating the report. 2016-06-30 23:59:59

Reporting API: Media Asset View Statistics

Provides detailed view statistics for a Media Library or Media Asset. The view statistics are aggregated by date and both the number of viewers and the total number of seconds viewed for the specified asset are returned. This API call may be made by either a user with Warpwire administrative access or by an authenticated user who is an administrator for the specified Media Library. The resource URL looks like this:

https://<API_URL>/api/stats/views/<MEDIA_LIBRARY>/o/<MEDIA_ASSET>/

This API call requires the following parameters:

Field Description Example
MEDIA_LIBRARY The UUID of the media library. This value is required F7E1419B- D480-474F-829E- AF53E5D475E2
MEDIA_ASSET The UUID of the media asset. To query for Media Library you should repeat the MEDIA_LIBARY UUID value. F7E1419B- D480-474F-829E- AF53E5D475E2

This API call supports the following optional parameters.

Field Description Example
start The beginning date range of the report. Refer to the Limiting Reporting Data section above. July2015
end The end date range of the report. Refer to the Limiting Reporting Data section above. December2018
limit Restrict the number of results to the specified value. 100
download Return the results in CSV format to be downloaded to the client. The output is not compressed. CSV Output File

An example request for media asset view statistics in Warpwire is as follows:

curl -u “username:password" “https://test.warpwire.com/api/stats/views/c/ F7E1419B-D480-474F-829E-AF53E5D475E2/o/F7E1419B-D480-474F-829E- AF53E5D475E2/?start=July2015&end=Decemeber2016&limit=100"

The following fields are returned in the media view statistics call:

Parameter Name Description Example
<DATE> A dynamic field that follows the convention YYYY-MM-DD (2015-05-25) [Indexed array] Specific information regarding each media asset (See below). [{viewers:25, seconds: 300}]
<DATE>[0].viewers Total number of unique viewers who watched the media asset during the specified time period. 25
<DATE>[0].seconds Total number of seconds the media asset was viewed during the specified time period. 300
start Fully formatted date that indicates the start value used for generating the report. 2014-06-01 00:00:00
end Fully formatted date that indicates the start value used for generating the report. 2016-06-30 23:59:59

Reporting API: Media Asset Play Statistics

Provides detailed play statistics for a Media Library or Media Asset. The play statistics are aggregated by date and both the number of plays and the total number of seconds viewed for the specified asset are returned. This API call may be made by either a user with Warpwire administrative access or by an authenticated user who is an administrator for the specified Media Library. The resource URL looks like this:

https://<API_URL>/api/stats/plays/<MEDIA_LIBRARY>/o/<MEDIA_ASSET>/

This API call requires the following parameters:

Field Description Example
MEDIA_LIBRARY The UUID of the media library. This value is required F7E1419B- D480-474F-829E- AF53E5D475E2
MEDIA_ASSET The UUID of the media asset. To query for Media Library you should repeat the MEDIA_LIBARY UUID value. F7E1419B- D480-474F-829E- AF53E5D475E2

This API call supports the following optional parameters.

Field Description Example
start The beginning date range of the report. Refer to the Limiting Reporting Data section above. July2015
end The end date range of the report. Refer to the Limiting Reporting Data section above. December2018
limit Restrict the number of results to the specified value. 100
download Return the results in CSV format to be downloaded to the client. The output is not compressed. CSV Output File

An example request for media asset view statistics in Warpwire is as follows:

curl -u “username:password" “https://test.warpwire.com/api/stats/plays/c/ F7E1419B-D480-474F-829E-AF53E5D475E2/o/F7E1419B-D480-474F-829E- AF53E5D475E2/?start=July2015&end=Decemeber2016&limit=100"

The following fields are returned in the media view statistics call:

Parameter Name Description Example
<DATE> A dynamic field that follows the convention YYYY-MM-DD (2015-05-25) [Indexed array] Specific information regarding each media asset (See below). [{viewers:25, seconds: 300}]
<DATE>[0].viewers Total number of unique viewers who watched the media asset during the specified time period. 25
<DATE>[0].seconds Total number of seconds the media asset was viewed during the specified time period. 300
start Fully formatted date that indicates the start value used for generating the report. 2014-06-01 00:00:00
end Fully formatted date that indicates the start value used for generating the report. 2016-06-30 23:59:59

View Developer APIs page