Visitor Sessions

Warning

This endpoint is experimental! It may be altered in the future.

This endpoint exposes visitor session database where sessions are stored each on one row. Through this endpoint you can query counts of arbitrary types of unique visitors and sessions, average distinct session URL counts, and average session durations of your own organization.

POST https://api.giosg.com/api/reporting/v1/orgs/<organization_id>/visitor_sessions

This endpoint returns:

• 200 if the request was successful
• 401 if you are not authenticated
• 403 if you do not have access to the organization
• 404 if the organization does not exist

Request payload (query definition)

An example request: "Count of unique visitors originating from Helsinki, Finland during 1.1.2019 (Helsinki time)."

POST https://api.giosg.com/api/reporting/v1/orgs/b0a1d32b-e82c-11e4-b081-6c4008adf7e8/visitor_sessions

{
  "interval": {
    "start": "2019-01-01T00:00:00.000+02:00",
    "end": "2019-01-01T23:59:59.999+02:00",
    "time_zone": "Europe/Helsinki"
  },
  "granularity": "all",
  "group_by": [],
  "aggregations": [
    {
      "type": "hyperUnique",
      "fields": ["visitor_id"]
    }
  ],
  "filters": {
    "type": "and",
    "fields": [
      { "type": "selector", "dimension": "country", "value": "Finland" },
      { "type": "selector", "dimension": "city", "value": "Helsinki" }
    ]
  }
}

Attribute	Type	Description
interval	Interval	Time interval of the query.
granularity	Granularity	Granularity of the query.
aggregations	[Aggregation, Aggregation, ...]	All different aggregations to be calculated in this query.
group_by	[Dimension, Dimension, ...]	All columns to be used in grouping the query results. Leave empty if you don't want to group by any dimension.
filters	[Filter]	Filter for selecting the session rows for the query.

Response payload (query result)

An example response

{
  "fields": [
    {
      "name": "timestamp",
      "type": "dimension"
    },
    {
      "name": "visitor_id_hyper_unique",
      "type": "metric"
    }
  ],
  "data": [["2019-01-01T00:00:00.000+02:00", 212.05452]]
}

Attribute	Type	Description
fields	[Field, Field, ...]	Field of the result.
data	[Datapoint, Datapoint, ...]	Values for fields in the same order as in fields array, one Datapoint for each bucket.

Available dimensions

Dimension	Description
browser_name	Name of the session's browser.
browser_version	Version of the session's browser.
city	City of the session.
country	Country of the session.
device_type	Type of the session's device. Possible values are "desktop", "tablet", and "mobile".
distinct_visited_urls	Array of unique visited URLs of the session. Contains maximum of 100 URLs.
distinct_visited_urls_count	Number of unique visited URLs of the session. This contains the real number of unique URLs, even if there are over 100 of them.
distinct_landing_urls	Array of unique landing URLs of the session, i.e. the first URL of the session on each host.
distinct_referrer_urls	Array of unique referrer URLs of the session.
distinct_search_terms	Array of unique search terms used in the session.
ip_organization	The name of the organization which owns the IP address of the session.
os_name	Name of visitor's operating system.
rooms	Array of unique room IDs the session happened in.
session_duration_secs	Duration of the session in seconds.
session_id	The unique ID of the session.
visitor_id	The unique ID of the visitor who owns this session.

Available aggregations

Type	Available for dimensions	Result type	Description
avg	"session_duration_secs", "distinct_visited_urls_count"	float	The average value of a dimension among the included sessions.
hyperUnique	"session_id", "visitor_id"	float	The cardinality of the dimension's values. Calculated using HyperLogLog algorithm. It introduces a maximum of 2% error in exchange for performance.
count	-	integer	The number of the included session rows. This aggregation type does not need fields defined, as it only calculates included rows.