This API produces aggregated histogram over the selected aggregation field (e.g. number of events) per specific values in the numerical event group as two arrays of numbers, e.g. 'events' (i.e. the number of events) and 'items' (i.e. the corresponding item values associated with the particular group). Consequently, if we denote the i-th number in the 'items' array as items(i) and the i-th number in the 'events' array as events(i), then events(i) represents the number of events for the item value that is greater than or equals to items(i) but smaller than items(i+1).
The API further allows to define the range of the histogram (that is the minimum and maximum item value) and the number of histogram buckets (i.e., array size). For example, given minimum value 0, maximum value 10, and count 5, the following figure demonstrates a visual interpretation of the results (note that the last bucket includes values that are less than max 10):
Unknown Attachment
The user must be authenticated and have read permissions to the given sites.
Current aggregation period and filter restrictions are as follows:
|
Period |
Groups available |
Filters available |
Notes |
|---|---|---|---|
|
Last 31 days or less |
Only ' |
All |
Only '
|
|
More than 31 days ago without long term storage |
None |
|
The data is unavailable for periods over 31 days, unless the sites are configured with long term support. |
|
More than 31 days ago with long term storage |
Only ' |
All |
Can be used only for a single site, i.e., when the number of sites is |
Request
Similar to /traffic/event. However, the 'orderBy' and history-related arguments are forbidden and the following additional arguments are supported:
|
Name |
Type |
Required |
Description |
|---|---|---|---|
|
|
Integer |
No |
The minimum value for the histogram, must be greater than or equal to 0. The default value is 0. |
|
|
Integer |
No |
The maximum value for the histogram, must be greater than or equal to ' |
|
|
Integer |
No |
The number of histogram buckets, must be between 1 and 1000. The default value is 10. |
|
|
Array of String |
No |
The specific groups to aggregate. The list cannot be empty. |
|
|
Array of String |
No |
The metrics to aggregate. The available field names are listed below. |
-
If '
groups' are not specified, the result is empty. The API performs faster when the number of specified groups is small. -
This API performs faster when the min-max range is small and the count is low.
Fields
Fields specify which metrics to aggregate. Currently, the following fields are supported:
|
Name |
Implicit |
Description |
|---|---|---|
|
|
Yes |
The number of events (i.e., page views). |
|
|
No |
The number of unique Cxense-specific identities, without consideration to the identities linked by the customer. For more information see the user identities demystification page . |
Only the events field is aggregated by default, the remaining fields have to be specified explicitly.
Response
The response object has the following fields:
Each group consists of a group name and the corresponding histogram:
|
Name |
Type |
Description |
|---|---|---|
|
|
String |
The name of the item. |
|
|
Object |
Contains the field names and arrays of aggregated numbers. |
Examples
Get a histogram for the scroll depth percentage last month. Limit the result to events with the scroll depth percentage between 0 and 10, and divide the result into 5 buckets.
$ python cx.py /traffic/histogram/event '{"siteId":"12345", "groups":["scrollDepth"], "start":"-1M", "count":5, "min":0, "max":10}'
{
"start": 1399377949,
"stop": 1402056349,
"groups": [
{
"data": {
"items": [
0,
2,
4,
6,
8
],
"events": [
25,
43,
36,
11,
78
]
},
"group": "scrollDepth"
}
]
}
Get a histogram for the scroll depth percentage last week. Limit the result to events with the scroll depth percentage between 5 and 20, and divide the result into 2 buckets.
$ python cx.py /traffic/histogram/event '{"siteId":"12345", "groups":["scrollDepth"], "start":"-1w", "count":2, "min":5, "max":20}'
{
"start": 1401452583,
"stop": 1402057383,
"groups": [
{
"data": {
"items": [
5,
11
],
"events": [
89,
34
]
},
"group": "scrollDepth"
}
]
}
Get a histogram for the scroll depth percentage last month. Limit the result to events with the scroll depth percentage between 0 and 10, and divide the result into 5 buckets.
$ python cx.py /traffic/histogram/event '{"siteId":"12345", "groups":["scrollDepth"], "fields":["uniqueUsers"], "start":"-1M", "count":5, "min":0, "max":10}'
{
"start": 1399377949,
"stop": 1402056349,
"groups": [
{
"data": {
"items": [
0,
2,
4,
6,
8
],
"events": [
25,
43,
36,
11,
78
],
"uniqueUsers": [
17,
34,
21,
7,
52
]
},
"group": "scrollDepth"
}
]
}