/traffic | Documentation

This top-level API aggregates the data originating from a given site or set of sites, and computes various metrics for a specified slice of traffic. The slice is defined by combining the time period with filters. Filters can be defined for properties and custom parameters associated with the incoming events, keywords in content profiles of the visited pages, or the users that generated the events. This API is useful for answering questions such as "find the number of events and the number of iPhone users from Oslo", where "iPhone users from Oslo" are the subject to filtering and the requested result is a set of metrics, i.e., the number of events and the number of unique users. For finding top-items of the respective types of data, see /traffic/event, /traffic/keyword and /traffic/custom.

The API also supports temporal bucketing of aggregated metrics, so that a single API request can be used to aggregate a time series, for example in order to plot how a given metric has varied over time.

The user must be authenticated and have read permissions to the specified sites.

Current aggregation period and filter restrictions are as follows:

Period	Fields available	Filters available	Notes
Last 31 days or less or as specified by long term storage	All	All
More than 31 days ago without long term storage	Only `events` and `sessionStarts`	None	The number of page views and the number of user sessions initiated in the specified period can be retrieved.

Our systems are designed for high availability and will sometime return numbers that can be slightly different when executed several times. Realtime requests for recent data for periods of seconds or minutes can sometimes see incomplete data, due to the nature of the internet and that events will enter our systems out-of-order. All data sent to our systems will eventually be counted, usually within 1 second, but can sometimes lag a little behind.We also keep several redundant clusters of servers in a shared-nothing setup, where historic data can differ slightly over time. The difference is usually less than 1% and is usually only seen on high traffic sites. This should be negligible error margin, and much smaller than other factors on the internet. This has usually to do with our de-duplication algorithm of events, which can miss when two duplicates arrive at different points in time.

Request

The request object has the following fields:

Name	Type	Required	Description
`siteIds`	Array of String	No	The set of sites to aggregate over.
`siteId`	String	No	The site to aggregate over. A more convenient alternative to `siteIds`, in the case of just one site.
`siteGroupIds`	Array of String	No	The set of site groups to aggregate over.
`siteGroupId`	String	No	The site group to aggregate over. A more convenient alternative to `siteGroupIds`, in the case of just one site group.
`start`	Integer or String	No	The start time of the aggregation period specified according to Traffic time specification . The default value is one hour ago.
`stop`	Integer or String	No	The stop time of the aggregation period specified according to Traffic time specification . The default value is right now. The stop time itself is excluded. `start` => traffic time period >`stop`
`filters`	Array of Object	No	Traffic filters to be applied. Conjunctive semantics (`and`) are assumed for the top-level filters.
`fields`	Array of String	No	The metrics to aggregate. The available field names are listed below.
`historyFields`	Array of String	No	The fields to aggregate a history for. Must be a subset of fields. Empty by default, i.e., no history data will be returned. While fields will only return a single value for the full period, history will return an array of values for intervals within the period. Useful when creating tables or graphs.
`historyBuckets`	Integer	No	The number of intervals for history aggregation. The time between `start` and `stop` will be divided into this many buckets or intervals. The default value is `10`, the maximum value is `2160`. Has effect only in combination with `historyFields`.
`historyResolution`	String	No	If defined, overrides `historyBuckets` and divides the time between `start` and `stop` into intervals of the given length. The acceptable values are `month`, `week`, `day`, `hour` and `minute`. The resulting number of buckets has to be between 2 and 2160. The resolution `minute` is not supported for data older than 31 days. See note below on how bucket calculation is affected by the provided `timeZone`.
`timeZone`	String	No	Client time zone to be used together with `historyResolution`. Default is UTC.
`origins`	Array of String	No	The specific origins to aggregate over. It can be specified only in combination with DMP filters (the filters starting with "`dmp-`") or for /dmp/traffic , /dmp/traffic/event , /dmp/traffic/custom requests. If not specified for these requests, all available/permitted origins are used.
`origin`	String	No	The origin to aggregate over. A more convenient alternative to `origins`, in the case of just one origin.

If historyResolution is day, we will attempt to make every bucket start at the same time of day as start. However, in the transition to and from daylight saving time, it may necessary to adjust the time. Similar considerations apply to the other resolutions. The provided timeZone is used when making these adjustments.

Fields

Fields specify which metrics to aggregate. Currently, the following fields are supported:

Name	Implicit	Description
`events`	Yes	The number of events (i.e., page views).
`uniqueUsers`	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 .
`activeTime`	No	The average active time on a page in seconds.
`urls`	No	The number of unique URLs.
`sessionStarts`	No	The number of events indicating the start of a user session.
`sessionStops`	No	The number of events indicating the stop of a user session.
`sessionBounces`	No	The number of sessions with only one event.
`scrollDepth`	No	The average scroll depth in percents.
`newUsers`	No	When a new user on a device visits a web site, an identfier is created and stored and recorded as part of a first page view. This does not show when global user identifiers is created.

Only the events field is aggregated by default, the remaining fields have to be specified explicitly.

Response

The response object has the following fields:

Name	Type	Description
`start`	Integer	The start time of the aggregation period in seconds, measured in Unix time .
`stop`	Integer	The stop time of the aggregation period in seconds, measured in Unix time .
`history`	Array of Integer	The start times of the aggregated history buckets. With n buckets, it contains (n + 1) values, where the last value is the stop time of the last bucket.
`data`	Object	The field names and aggregated numbers.
`historyData`	Object	The field names and lists of aggregated numbers.

Examples

The number of events collected in the last two hours

Bash

$ python cx.py /traffic '{"siteId":"12345", "start":"-2h"}'
{
 "start": 1416288121,
 "stop": 1416295321,
 "data": {
 "events": 1777
 }
}

The number of events, unique users, average active time and the number of pages visited by desktop users in the last hour

Bash

$ python cx.py /traffic '{"siteId":"12345", "fields":["uniqueUsers","activeTime","urls"], "filters":[{"type":"event","group":"deviceType","item":"Desktop"}]}'
{
 "start": 1416291628,
 "stop": 1416295228,
 "data": {
 "activeTime": 0,
 "uniqueUsers": 312,
 "events": 314,
 "urls": 93
 }
}

The number of events, unique users and session starts, including a history for the number of events and session starts (divided into 5 buckets)

Bash

$ python cx.py /traffic '{"siteId":"12345", "fields":["uniqueUsers","sessionStarts"], "historyFields":["events","sessionStarts"], "historyBuckets":5}'
{
 "start": 1416291786,
 "stop": 1416295386,
 "data": {
 "uniqueUsers": 994,
 "events": 1049,
 "sessionStarts": 998
 },
 "historyData": {
 "events": [
 231,
 224,
 248,
 220,
 126
 ],
 "sessionStarts": [
 227,
 212,
 232,
 206,
 121
 ]
 },
 "history": [
 1416291786,
 1416292506,
 1416293226,
 1416293946,
 1416294666,
 1416295386
 ]
}

The number of users with Flash installed and the corresponding event count

Bash

$ python cx.py /traffic '{"siteIds":["12345"], "fields":["uniqueUsers"], "filters":[{"type":"event","group":"capability","item":"flash"}]}'
{
 "start": 1416291900,
 "stop": 1416295500,
 "data": {
 "uniqueUsers": 1,
 "events": 1
 }
}

The number of iPhone users and the corresponding event count, number of unique URLs, and the average active time

Bash

$ python cx.py /traffic '{"siteIds":["12345"], "fields":["uniqueUsers","activeTime","urls"], "filters":[{"type":"event","group":"os","item":"iPhone OS"}]}'
{
 "start": 1416291975,
 "stop": 1416295575,
 "data": {
 "activeTime": 27.0,
 "uniqueUsers": 128,
 "events": 130,
 "urls": 69
 }
}

The number of events per month since June 1st 2014 (timezone UTC -06:30)

Bash

$ python cx.py /traffic '{"siteIds":["12345"], "start":"2014-06-01T00:00:00.0-0630", "historyFields":["events"], "historyResolution":"month"}'
{
 "start": 1401604200,
 "stop": 1416295500,
 "data": {
 "events": 2594238
 },
 "historyData": {
 "events": [
 543992,
 267536,
 556117,
 517908,
 449113,
 259572
 ]
 },
 "history": [
 1401604200,
 1404196200,
 1406874600,
 1409553000,
 1412145000,
 1414823400,
 1416295500
 ]
}

Last updated: December 10, 2024