giosg Reporting - HTTP API - Common Concepts

Modern reporting APIs, e.g. Chat Sessions API and Visitor Sessions API, are more flexible in terms of querying. They allow you to build your query to match more accurately to the question you are asking, but consequently, writing the query will be more complex.

Here are listed few common concepts regarding modern reporting APIs.

Dimension

Dimension describes a column in the table in question. Each dimension can be used for filtering and grouping, but only some dimensions have aggregations available. Available dimensions and aggregations are listed for each endpoint.

In query response, the dimensions in "fields" will define the order for datapoint values.

Example query response dimensions in buckets of day and country:

{
    "fields": [
        {
            "name": "timestamp",
            "type": "dimension"
        },
        {
            "name": "country",
            "type": "dimension"
        },
        {
            "name": "count",
            "type": "metric"
        },
    ]
}

Datapoint

Datapoint is an array for a single data bucket in the query response. The elements of each datapoint array are in the same order as dimensions in fields array.

Example query response datapoints in buckets of day and country, i.e. this query was done with granularity of day and grouped by dimension "country":

{
    "data": [
        [
            "2019-01-01T00:00:00.000Z",
            "Finland",
            212
        ],
        [
            "2019-01-01T00:00:00.000Z",
            "Sweden",
            140
        ],
        [
            "2019-01-02T00:00:00.000Z",
            "Finland",
            210
        ],
        [
            "2019-01-02T00:00:00.000Z",
            "Sweden",
            145
        ]
    ]
}

Interval

Definition for the time range of rows to be included in the query. All timestamps can contain any offset. The value of time_zone will be used to determine the starting times of time buckets. The default value for time_zone is "UTC".

Example interval

{
    "interval": {
        "start": "2019-01-01T00:00:00.000+02:00",
        "end": "2019-01-02T00:00:00.000+02:00",
        "time_zone": "Europe/Helsinki"
    }
}

Attribute	Type	Description
start	ISO-8601 timestamp	Starting time of the interval.
end	ISO-8601 timestamp	Ending time of the interval.
time_zone	Time zone in tz database format	Time zone, which is used in queries with smaller than "all" granularity, to group data in time buckets.

Granularity

Definition for the size of the time buckets in which the query result is grouped in.

Example granularity

{
    "granularity": "minute"
}

Possible values are: "all", "minute", "fifteen_minute", "thirty_minute", "hour", "day", "week", "month", or "year".

Aggregation

Definition for aggregations to be calculated in the query.

Example aggregations

{
    "aggregations": [
        {
            "type": "hyperUnique",
            "fields": ["session_id", "visitor_id"]
        },
        {
            "type": "count"
        },
        {
            "type": "avg",
            "fields": ["session_duration_secs", "distinct_visited_urls_count"]
        },
    ]
}

Attribute	Type	Required	Description
type	string	True	The type of the aggregation. Listed under heading "Available aggregations" for each endpoint.
fields	[Dimension, Dimension, ...]	False	The dimensions to calculate this aggregation for. Not every type of aggregation can be calculated for all available fields. See Available aggregations of each endpoint for all possible combinations.

Filter

Filters are used to limit the session rows to be included in the query. You can filter rows by any field described in "Available dimensions" section of an endpoint. There are multiple filter types:

Type selector should be used for simple equality comparisons.

Selector

{
    "filters": {
        "type": "selector",
        "dimension": "country",
        "value": "Finland"
    }
}

Parameter | Type | Required | Description :---------------|:------------------------|----------|---------- type | "selector" | True | Always "selector". dimension | Dimension | True | Dimension value | string, number | True | Value which should exactly match to the value in Dimension on desired rows.

And

Type and should be used for checking multiple conditions.

{
    "filters": {
        "type": "and",
        "fields": [
            {"type": "selector", "dimension": "country", "value": "Finland"},
            {"type": "selector", "dimension": "city", "value": "Helsinki"}
        ]
    }
}

Parameter | Type | Required | Description :---------------|:------------------------|----------|---------- type | "and" | True | Always "and". fields | [Filter, Filter, Filter...] | True | Filters which are included inside AND clause

Or

Type or should be used for checking or conditions.

{
    "filters": {
        "type": "or",
        "fields": [
            {"type": "selector", "dimension": "country", "value": "Finland"},
            {"type": "selector", "dimension": "country", "value": "Sweden"}
        ]
    }
}

Parameter | Type | Required | Description :---------------|:-----------------------|----------|---------- type | "or" | True | Always "or". fields | [Filter, Filter, Filter...] | True | Filters which are included inside OR clause

Regex

Type regex can be used to execute reqular expression queries.

{
    "filters": {
        "type": "regex",
        "dimension": "country",
        "pattern": "Finland|Sweden|Norway"
    }
}

Parameter | Type | Required | Description :---------------|:------------------|----------|---------- type | "regex" | True | Always "regex". dimension | Dimension | True | Dimension pattern | string | True | Pattern to match for values in dimension.

Not

Type not can be used to execute negation queries. This returns results which do not match with the filter.

{
    "filters": {
        "type": "not",
        "field": {
            "type": "selector",
            "dimension": "country",
            "value": "Finland"
        }
    }
}

Parameter	Type	Required	Description
type	"not"	True	Always "not".
dimension	Dimension	True	Dimension
value	string, number	True	Value which should not exist on the desired rows.

Bound

Type bound can be used to execute comparison queries.

{
    "filters": {
        "type": "bound",
        "dimension": "distinct_visited_urls_count",
        "lower": "50",
        "lowerStrict": true,
        "upper": "100",
        "upperStrict": false,
        "ordering": "numeric"
    }
}

Parameter	Type	Required	Description
type	"bound"	True	Always "bound".
dimension	Dimension	True	Dimension to check the boundaries for.
upper	string	False	Limit for "less than or equal" boundary.
upperStrict	Boolean	False	If true, upper limit comparison is done as "less than", not "less than or equal".
lower	string	False	Limit for "greater than or equal" boundary.
lowerStrict	Boolean	False	If true, upper limit comparison is done as "greater than", not "greater than or equal".
ordering	"lexicographic", "alphanumeric", "numeric", "strlen", "version"	True	Specifies the type of comparison used when checking the boundaries. See option descriptions

Filters can be nested. Below query would match events whose field country is either Finland or Sweden, field city is either Helsinki or Stockholm and field browser_name contains either Chrome or Chrome Mobile.

{
    "filters": {
        "type": "and",
        "fields": [
            {
                "type": "or",
                "fields": [
                    {"type": "selector", "dimension": "country", "value": "Finland"},
                    {"type": "selector", "dimension": "country", "value": "Sweden"}
                ]
            },
            {
                "type": "or",
                "fields": [
                    {"type": "selector", "dimension": "city", "value": "Helsinki"},
                    {"type": "selector", "dimension": "city", "value": "Stockholm"}
                ]
            },
            {"type": "regex", "dimension": "browser_name", "pattern": "Chrome( Mobile|)"}
        ]
    }
}