COVERITLIVE API - EVENT/STATS (V. 2.0)

The Request

This method allows users to retrieve statistics for a CoveritLive event. Statistics can only be retrieved for events that are in a completed (aka finished) state. Available stats include total page views, total clicks, average duration, and detailed click and page view numbers by day.

URL:
https://api.coveritlive.com/remote/2/event/stats
Response Format:
JSON
HTTP Method(s):
GET
API Rate Limited:
false
In addition to the parameters listed in the Request Parameters section, the event/stats method also includes the following parameters:

Parameter Description Required
event_code The event code for the event for which stats are being retrieved. Each CiL event that is created is assigned a unique event code that identifies it in the database - The event owner can find this value after creating a new event, by selecting the "altcast_code" which is found in their Viewer Window embed code (e.g. the event code is "46e6cd22b5" in "altcast_code=46e6cd22b5"). This value is also returned by the event/list and event/create API methods. yes

The Response

The stats data is returned in the data field of a general response. The data returned consists of a json object with the following fields:

Field Name Field Value(s) Explanation
total_live_page_views {integer} The total number of page views that an event received while it was live. Page views include any readers who viewed the event page.
total_live_clicks {integer} The total number of clicks that an event received while it was live. Clicks are a subset of page views, and include any readers who interacted with the event (by clicking on the event, scrolling, submitting a comment, etc ...)
total_completed_page_views {integer} The total number of page views that an event received while it was in a completed state (also known as a replay).
total_completed_clicks {integer} The total number of clicks that an event received while it was in a completed state (also known as a replay). Clicks are a subset of page views, and include any readers who interacted with the event (by clicking on the event, scrolling, etc ...)
average_duration {float} The average length of time (in minutes) that readers spent watching / participating in the event. The calculation only includes readers who spent more than 1 minute at the event.
daily_data {Array} An array of daily stats objects that include page view and click data broken down by day. The sum of the individual fields in the daily stats objects will equal the corresponding total field. For example, the sum of the live_page_views fields in the daily stats object will equal the total_live_page_views field.

Daily stats objects have the following fields:

Field Name Field Value(s) Explanation
date {string} The date that the stats in the daily stat object were recorded. Represented as a string in the following format: "YYYYMMDD".
live_page_views {integer} The total number of page views that an event received on the specified date (while it was live). Page views include any readers who viewed the event page.
live_clicks {integer} The total number of clicks that an event received on the specified date (while it was live). Clicks are a subset of page views, and include any readers who interacted with the event (by clicking on the event, scrolling, submitting a comment, etc ...)
completed_page_views {integer} The total number of page views that an event received on the specified date (while it was in a completed state).
completed_clicks {integer} The total number of clicks that an event received on the specified date (while it was in a completed state). Clicks are a subset of page views, and include any readers who interacted with the event (by clicking on the event, scrolling, etc ...)

Example response to a successful event/stats request:


{
	"result" : "success",
	"message" : "true",
	"type" : "event",
	"action" : "stats",
	"version" : 2,
	"data" : {
		"total_live_page_views" : 1341
		"total_live_clicks" : 1275
		"total_completed_page_views" : 162
		"total_completed_clicks" : 48,
		"average_duration" : 36.5,
		"daily_data":[
			{
				"date":"20120205",
				"live_page_views":742,
				"live_clicks":708,
				"completed_page_views":0,
				"completed_clicks":0
			},
			{
				"date":"20120206",
				"live_page_views":599,
				"live_clicks":567,
				"completed_page_views":127,
				"completed_clicks":39
			},
			{
				"date":"20120207",
				"live_page_views":0,
				"live_clicks":0,
				"completed_page_views":13,
				"completed_clicks":4
			},
			{
				"date":"20120208",
				"live_page_views":0,
				"live_clicks":0,
				"completed_page_views":14,
				"completed_clicks":5
			},
			{
				"date":"20120209",
				"live_page_views":0,
				"live_clicks":0,
				"completed_page_views":3,
				"completed_clicks":0
			},
			{
				"date":"20120228",
				"live_page_views":0,
				"live_clicks":0,
				"completed_page_views":3,
				"completed_clicks":0
			},
			{
				"date":"20121129",
				"live_page_views":0,
				"live_clicks":0,
				"completed_page_views":2,
				"completed_clicks":0
			}
		]
	}
}

event/stats Error Responses

A variety of error responses (in addition to the common error responses) to event/stats requests, and instructions on how to rectify them:

result response message response solution
event_not_completed The event specified by the event code is not in a completed state. event/stats requests can only be applied to events that are in a completed (aka finished) state.