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