The statistics command contains all actions related to statistics about views on the different types of items available in the platform (Item, LiveStream, Account). This API is a read-only API.
The following fields are used in most of the statistics actions:
|views||The number of times a unique user viewed the requested statistics item. A single user viewing the requested statistics item again after a longer period counts as a new view|
|bytes||The number of bytes for all requests in the requested window for the statistics item.|
|plays||The number of times a user started playing this statistics item. This will be reported by the video player.|
|impressions||The number of times the requested statistics item is displayed to a user. The video player will report this. This does not mean the item has been played. If a website displays the item, but the user does not click the play button (i.e. does not play the item), this will be counted for impressions, but not for plays.|
|impressionsab||The same number as for impressions, but only for impressions where an active ad blocker was detected on the user’s side. These will also be counted under impressions above. The video player will report this.|
|avgsecondsviewed||The average number of seconds that a viewer has viewed in a specific bin. The video player will report the number of seconds viewed, and this total number for each bin is divided by the number of viewers in that bin, before aggregating and averaging it into the selected time granularity. This value is reported for LiveStreams only.|
|secondsviewed||The number of seconds this stream has been viewed in a specific bin. The video player reports this periodically. This value is reported for LiveStreams only.|
|avgviewers||The average number of viewers that have been active in a specific bin . A viewer is counted in a bin if the the video player reports a relevant event. This value is reported for LiveStreams only.|
|adimpressions||The number of times an ad has been loaded by the user / video player. This does not mean the ad has been played. The video player will report this.|
|adstarts||The number of times an ad started playing to the user. The video player will report this.|
|adskips||The number of times a user has chosen to skip an ad which was skippable. The video player will report this.|
|adcompletes||The number of times an as has been completely played to the user, so without having been skipped, not having been skippable and not otherwise interrupted by user action or other means. The video player will report this.|
|adclicks||The number of times an ad has been clicked by the user. This will only be reported in case the ad has a clickURL defined. The video player will report this.|
The following remarks apply to all actions:
Some resolutions may be unavailable. The smallest resolution that will be returned is the one the stats were recorded in. Selecting a lower resolution will return the smallest available resolution.
Input ranges are extended to coincide with resolution boundaries if they are not aligned yet. The start range will be extended to an earlier time and the end range to a later time. For example, selecting statistics for a certain day between 12:34:45 and 13:33:37 with a resolution of 15 minutes will result in the effective range being extended to span 12:30:00 up to but not including 13:45:00.
Some combinations of filters may yield less than the requested number of results or even no results at all. It is up to the user of the API to handle this condition.
It is possible to filter on one client or client group and it is possible to get the top stats from one client / client group. Filtering on client and client groups is not supported for hotspots.
Note that for aggregates and top statistics, if no filters on specific items or livestreams are given, those actions will return statistics for everything the current actor has access to. This means that if those actions are performed with an account, they will return the statistics for that account and if performed with a customer it will return everything for that customer.
Also note that if the aggregates or top statistics of an account or customer are requested that this will also contain data for items that are now deleted but do contain statistics in the given range. For example, if an item is deleted on 10-05-2015 and the statistics of the account that item belongs to are requested for the range 06-05-2015 - 09-05-2015 it will contain data for that item (if it actually contains statistics within that range).
It is also possible to include deleted items and live streams when viewing the statistics of a specific item / live stream or all items / live streams (i.e. when passing item, livestream, type=item or type=livestream to the API) by setting alsodeleted to true.
The following actions are defined for this command: