Hotspots

Returns hotspot statistics for specific items, aggregated per day. These results are always in the platform timezone.

A hotspot is defined as part of an item between two checkpoints. A checkpoint happens every 10%, starting at 0% and ending at 100%. The platform keeps track of how many times a checkpoint is passed. It also keeps track of the seconds viewed per hotspot. Note that hotspot and bin are used interchangeable.

Because there is a discrepancy between checkpoints and bins, this action will return its data in the following way:

Tokens

This action requires the following tokens:

  • stats-view

Arguments

Required arguments are marked in bold, and optional arguments are marked in italics.

Argument Type Default Description
item Hash   Only show hotspot stats for this specific item. If omitted, shows hotspot stats for all items
alsodeleted Boolean false If set to true, also view the statistics of items and livestreams that are deleted
resolution String day

The resolution to use for these stats

This argument can only contain one of the following values:

  • day
  • week
  • month
  • year
  • all
start DateTime   The start of the range to get the stats from. If omitted, return stats from the first moment available. Required if resolution is not all
end DateTime   The end of the range to get the stats from. If omitted, return stats until the last moment available. Required if resolution is not all. If there would be more than 10000 periods of the given resolution between start and end date, this will be considered as an input error

Output

This action produces the following extra headers on success, besides the default headers:

Name Type Description
firstdate DateTime The earliest date that stats are available for the provided arguments. The start date will take into account the creation of specific items and live streams if provided and it will never return a date below the date the account or customer was created, if these are supplied. Requesting stats for the current arguments before this date will thus not return anything
lastdate DateTime The latest date that stats are available for the provided arguments. Requesting stats for the current arguments after this date will thus not return anything
resolution String The resolution of the output. This might be lower

This action produces the following output on success:

An array containing zero or more elements, each one being an object containing the following fields:

Name Type Description
period

Information about the period of this row

The value of this field is an object containing the following fields:

Name Type Description
begin DateTime Begin of the stats-period
end DateTime End of the stats-period
hotspots

All the information about hotspots in this period

The value of this field is an array containing zero or more elements, each one being an object containing the following fields:

Name Type Description
bin

Information about the range of this bin

The value of this field is an object containing the following fields:

Name Type Description
begin Integer Begin of the Hotspot bin (percentage). This can be -10 to denote the bin that monitors the number of times the begin-checkpointis passed
end Integer End of the Hotspot bin (percentage)
checks Integer Number of times the checkpoint for this bin was passed. The checkpoint is defined as the begin of the bin
secondsviewed Integer The total number of seconds viewed in this bin. Will always be 0 for the -10%-0% bin

Errors

This action can return one of the default status codes, or one of the following status codes on error:

STATUS_STATS_RANGE_INVALID (390)
An invalid time selection range was supplied (spans zero or negative time)