QueryAPI v2 - Webhits Event counter queries

On this page you find detailed information about the Keytiles Query API v2 - Event counter query results so you can better understand how to make requests and how to interpret the response.

Content of this page

• # API definition
• # Returned event counters and their meaning
• # Glossary
• # Formulas - How do I calculate things from "newVisitors" and "bounceVisitors" counters?

API definition

We maintain OpenApi definitions in a public Git repository.

Returned event counters and their meaning

eventCountTotal

The sum of events Keytiles counted - within the query range, matching all filters (*Only parameters) of your query.

This counter is always returned in the response.

eventCountDirect

Within eventCountTotal this many events came from visitors who visited your page directly. So there was no referrer.

You find more info about referrer classification here.

This counter is only returned if you specified interest=referrerCounts - see API definition for more details!

eventCountSearchReferrer

Within eventCountTotal this many events came from visitors who visited your page coming from "Search" engines.

You find more info about referrer classification here.

This counter is only returned if you specified interest=referrerCounts - see API definition for more details!

eventCountSocialReferrer

Within eventCountTotal this many events came from visitors who visited your page coming from "Social" websites.

You find more info about referrer classification here.

This counter is only returned if you specified interest=referrerCounts - see API definition for more details!

eventCountLinkReferrer

Within eventCountTotal this many events came from visitors who visited your page coming from another website which is not "Search" engine neither "Social" website but something else.

You find more info about referrer classification here.

This counter is only returned if you specified interest=referrerCounts - see API definition for more details!

eventCountCampaignReferrer

Within eventCountTotal this many events came from recognized Campaigns.

You find more info about campaign tracking here.

This counter is only returned if you specified interest=referrerCounts - see API definition for more details!

eventCountNoSession

Within eventCountTotal this many cases we know for sure Keytiles were not able to build up a Visit Session.

This could happen because of multiple reasons. If you want to understand it better then you find more info about how Visit Session building works here. Go and read about it!

For now the point is that if Keytiles can not build a Visit Session then it has some consequences. In this case

1. Term like "bouncer visit" also does not make any sense. We simply don't know if a visitor is a bouncer or not. Meaning eventCountBounceVisitor and eventCountBounceNewVisitor is not incremented / counted in these cases.
2. Visit Session related counters namely visitSessionStartedCount or visitSessionEventFirstOfTypeCount also can not be incremented / counted.

Thus if you are observing any of the above counters then you need to use the eventCountTotal - eventCountNoSession formula to basically calculate the 100% of cases where these counters make sense to compare to.

This counter is only returned if you specified interest=visitSession - see API definition for more details!

eventCountUnknownNewVsRetVisitor

Within eventCountTotal this many cases we know for sure Keytiles were NOT able to recognize if the visitor is "new" or "returning" visitor. This happens due to missing visitor consent to identify the device.

Recognizing "returning" visitors and distinguish them from "new" visitors is just working if Keytiles can identify the device the visitor is using 100% certainty. This means 

• our tracking script - which is added to your website - is allowed to place the "kt_uniqueWebClientId" cookie - due to visitor consent.
  or
• in case your iOS/Android app is integrated with our Hit Collection API then you are sending "uniqueWebClientId" along with the hit data (in this case implementing device identification complying with visitor consent is App responsibility)

When "returning" vs "new" visitors can not be distinguished then eventCountNewVisitor and eventCountBounceNewVisitor counters are impacted (note: this latter one is also impacted by eventCountNoSession!). They are not counting these events.

eventCountNewVisitor

Please read the description of eventCountUnknownNewVsRetVisitor first!

Within eventCountTotal - eventCountUnknownNewVsRetVisitor this many events came from "new" visitors.

eventCountBounceVisitor

Please read the description of eventCountNoSession first!

When Keytiles can build Visit Session then this many events came from "bouncer" visitors (who just did one action so far) all together so far.

eventCountBounceNewVisitor

Please read the description of eventCountNoSession and eventCountUnknownNewVsRetVisitor first!

If Keytiles can track "new" vs "returning" visitors AND also can build Visit Session then this many events came from "bouncer" (who just did one action so far) and "new" visitors.

eventCountBounceUnknownNewVsRetVisitor

Please read the description of eventCountNoSession and eventCountUnknownNewVsRetVisitor first!

If Keytiles can build Visit Session BUT it can not distinguish "new" vs "returning" visitors then this many events came from "bouncer" (who just did one action so far)

visitSessionStartedCount

Please read the description of eventCountNoSession first!

Within eventCountTotal - eventCountNoSession this many events were the very first event coming from the same visitor. Meaning: the number of started Visit Sessions.

visitSessionEventFirstOfTypeCount

This counter is definitely an advanced topic - requires from you a bit deeper understanding of things. Please read the description of eventCountNoSession first!

OK if you are still here...

Keytiles is capable of tracking different type of events - which also known as "event based tracking". This helps you to go with the concept of "micro conversions". You can find more info about even based tracking here.

This value in concept is similar to visitSessionStartedCount but different in a sense it is distinguished per Event Types. It's easier to understand the meaning through a simple example.

Let's assume a visitor arrives to your website and generating the following sequence of events:

1. "pageview"
2. "pageview"
3. "download"
4. "pageview"

In this case the Visit Session was started by a "pageview" event. visitSessionStartedCount was increased at hit #1 - as a new Visit Session was started at this point. So far clear.

At hit #1 the visitSessionEventFirstOfTypeCount was also increased - as this hit was the first hit in this new Visit Session with Event Type "pageview".

For hit #2 nothing happens.

But for hit #3 - as first "download" Even Type in the Visit Session - the visitSessionEventFirstOfTypeCount is increased again - associated with event type "download" - while visitSessionStartedCount not increased (the session was already started by hit #1).

So to put it this way: this counter gives you an idea about "how many different Event Types is used by my visitors within one Visit Session?"

Please note! This number can just be measured by Keytiles in those cases where Keytiles can build up a Visit Session. You find more info about how it works here. 

Glossary

Formulas - How do I calculate things from "newVisitors" and "bounceVisitors" counters?

When you want to know answers for questions related to "bouncer" vs "non-bouncer" and "new" vs "returning" visitors and you specify interest=newVisitors or interest=bounceVisitors or both interest=bounceVisitors,newVisitors then Keytiles query gives you counters like:

• eventCountNoSession
• eventCountUnknownNewVsRetVisitor
• eventCountNewVisitor
• eventCountBounceVisitor
• eventCountBounceNewVisitor
• eventCountBounceUnknownNewVsRetVisitor

It is absolutely not trivial to see how can you calculate answers for your questions... :-) Yes we know it! We did some math around it in order to minimize the information we need to store still you can answer all your questions from this data.

In this section we give you some tables which might help you to use the appropriate formula to find out answer for all your possible questions!

Simple “new vs returning” calculations

Here are some formulas for how to calculate answer for your questions related to "new" and "returning" visitors from returned Counters when interest=newVisitors is added.

my question “new” vs “returning”	Formula to use
unknown	eventCountUnknownNewVsRetVisitor
ratio of unknown	eventCountUnknownNewVsRetVisitor / eventCountTotal
known	eventCountTotal - eventCountUnknownNewVsRetVisitor
ratio of known	(eventCountTotal - eventCountUnknownNewVsRetVisitor) / eventCountTotal
from this point - everything makes sense only within the known part!
“new”	eventCountNewVisitor
“returning”	known - eventCountNewVisitor
ratio of “new”	eventCountNewVisitor / known
ratio of “returning”	(known - eventCountNewVisitor) / known

Simple “bounce vs non-bounce” calculations

Here are some formulas for how to calculate answer for your questions related to "bounce" and "non-bounce" visitors from returned Counters when interest=bounceVisitors is added.

my question “bounce” vs “non-bounce”	Formula to use
unknown	eventCountNoSession
ratio of unknown	eventCountNoSession / eventCountTotal
known	eventCountTotal - eventCountNoSession
ratio of known	(eventCountTotal - eventCountNoSession) / eventCountTotal
from this point - everything makes sense only within the known part!
“bounce”	eventCountBounceVisitor
“non-bounce”	known - eventCountBounceVisitor
ratio of “bounce”	eventCountBounceVisitor / known
ratio of “non-bounce”	(known - eventCountBounceVisitor) / known

“bounce” vs “non-bounce” within “new” vs “returning” values

coming... we are still verifying our formulas!