Groupings

Groupings are properties of website visits and tracked events that can be used to arrange data, for example, OS or device type applied by website visitors, as well as their location. In requests to HTTP Report API, the groupings are set in the group parameter.

Let's have a look at a report on website visitors in terms of device types:

Device type

Visitors

Desktop

790

Mobile

862

Tablet

236

Device type is used as a grouping here. It is a visit property used to combine data. Visitors is a metric calculated on the basis of the website visits.

All groupings are divided into several categories by data type:

Audience #

Grouping

Type

Description

country #

integer

Visitor's country in the form of a two-digit ID (ISO 3166-1).

region #

integer

Visitor's region in the form of a two-digit alphanumeric ID.

 

For example, CA stands for the U.S. state of California.

 

The full list of IDs is available in file . When searching by region, make sure to specify a country as well (the country parameter) since different countries may have similar region IDs.

city #

integer

Visitor's city should be specified in full, for example, Dallas, Moscow.

language #

integer

Visitor's language in the form of a two-digit ID (ISO 639-1), for example:

  • en – English
  • ru – Russian
  • it – Italian
  • es – Spanish
  • de – German
  • etc.

user_agent #

string

Visitor's full user-agent name.

 

For example, Mozilla/5.0 (Windows NT 10.0; Win64; x64; rv:63.0) Gecko/20100101 Firefox/63.0.

ua_bot_name #

string

Bot name.

 

This grouping allows you to combine traffic data from various automated agents, like search bots (Googlebot, YandexBot, etc.).

ua_bot_version #

string

Bot version, for example, 2.0.

 

Using this grouping with ua_bot_name, you can request data for a specific version of a search bot, for example, Gogglebot 2.1.

ua_client #

integer

Browser/application name from user-agent: Chrome, Safari, Firefox, Edge, IE, Opera, Yandex, Facebook App, Instagram App, Google App, Pinterest App, WeChat App, Other.

ua_client_class #

integer

Client type from user-agent: Browser, Application.

ua_client_name #

string

Client name from user-agent, for example, Firefox, Goggle App, Opera, etc.

 

This grouping is more detailed compared to ua_client. For example, when ua_client=other (this category features less popular applications), ua_client_name may indicate "QQbrowser".

 

You can find possible values in the Audience\Platforms website report of the Finteza panel. They are available in the Application section.

ua_client_version #

string

Client version from user-agent. Using this grouping with ua_client_name, you can request data for a specific version, for example, Mozilla/5.0.

ua_os #

integer

OS type from user-agent: Windows, Linux, Mac, Android, iOS, Other.

ua_os_version #

string

OS version.

 

Specified in full, for example, Windows 10, Windows 2003 Server, Mac OS, Linux (Ubuntu), etc.

ua_device #

integer

Device type: Desktop, Mobile, Tablet, Other.

ua_device_model #

string

Device model.

 

You can find possible values in the Audience\Devices website report of the Finteza panel. They are available in the Model section.

ua_device_brand #

string

Device manufacturer.

 

You can find possible values in the Audience\Devices website report of the Finteza panel. They are available in the Brand section.

screen #

string

Visitor's screen resolution in pixels as {width}x{height}, for example, 1024x768.

Events #

Grouping

Type

Description

tracking_event #

string

Tracked event name.

Pages #

Grouping

Type

Description

page_title #

string

Header of the web page a user is located at.

request_source_type #

integer

Traffic source type:

  • 0 – unknown traffic
  • 1 – direct visits
  • 2 – referral traffic
  • 3 – search traffic
  • 4 – traffic from social networks
  • 5 – internal transitions

request_source_domain_alias #

string

Referring source name.

 

The parameter sets a short name (for example, google, facebook, yandex, etc.) rather than a source address.

 

Possible values can be found in the Sources\Search and Sources\Social website report of the Finteza panel.

source_type #

integer

Traffic primary source type:

  • 0 – unknown traffic
  • 1 – direct non-advertising visits
  • 2 – referral non-advertising traffic
  • 3 – non-advertising traffic from search engines
  • 4 – non-advertising traffic from social networks
  • 5 – internal non-advertising transitions
  • 99 – advertising visits

Unlike request_source_type, all advertising traffic here is allocated in a separate category.

source_domain #

string

Referring primary source address.

source_domain_alias #

string

Referring primary source name.

 

The parameter sets a short name (for example, google, facebook, yandex, etc.) rather than a source address.

 

Possible values can be found in the Sources\Search and Sources\Social website report of the Finteza panel.

source_is_freezed #

integer

This flag is inserted into all visitors' requests as soon as they perform a conversion action.

 

In other words, all requests from already converted visitors are marked with it.

source_is_freezing #

integer

This flag is inserted into one request used by a visitor to perform a conversion action.

 

This property allows tracking how many conversions occurred over a certain period of time.

referrer_protocol #

string

Name of a protocol from the address of a web page a visitor is located at.

 

For example, in https://abc-site.com, the referrer_protocol value is "https".

referrer_domain #

integer

Name of a domain from the address of a web page a visitor is located at.

 

For example, in https://abc-site.com, the referrer_domain value is "abc-site.com".

referrer_path #

string

Internal path from the address of a web page a visitor is located at (without parameters and anchor).

 

For example, in https://abc-site.com/page1#section1, the referrer_path value is "page1".

referrer_anchor #

string

Anchor (hash) from the address of a web page a visitor is located at.

 

For example, in https://abc-site.com#section1, the referrer_anchor value is "section1".

referrer_params #

string

Additional parameters from the address of a web page a visitor is located at.

 

For example, in https://abc-site.com#section1?param1=value1&param2=value2, the referrer_params value is "param1=value1&param2=value2".

back_referrer_protocol #

string

Name of a protocol from the address of a web page a visitor was located at before performing a tracked action (referrer) .

 

For example, in https://abc-site.com, the back_referrer_protocol value is "https".

back_referrer_domain #

integer

Name of a domain from the address of a web page a visitor was located at before performing a tracked action (referrer).

 

For example, in https://abc-site.com, the back_referrer_domain value is "abc-site.com".

back_referrer_path #

string

Internal path from the address of a web page a visitor was located at before performing a tracked action (referrer).

 

For example, in https://abc-site.com/page1#section1, the back_referrer_path value is "page1".

back_referrer_anchor #

string

Anchor (hash) from the address of a web page a visitor was located at before performing a tracked action (referrer).

 

For example, in https://abc-site.com#section1, the back_referrer_anchor value is "section1".

back_referrer_params #

string

Additional parameters from the address of a web page a visitor was located at before performing a tracked action (referrer).

 

For example, in https://abc-site.com#section1?param1=value1&param2=value2, the referrer_params value is "param1=value1&param2=value2".

next_referrer #

string

Address of an external web page a user moved to from your website.

 

It is used to track clicks on external links located on your website.

 

Data on such transition can be found in Pages\Exits\External links website report of the Finteza panel.

next_referrer_domain #

string

Domain name from the next_referrer value.

 

For example, in https://abc-site.com, the next_domain value is "abc-site.com".

Traffic #

Grouping

Type

Description

session #

integer

Visitor's session ID as a numeric value, for example, 1551232514995740556.

 

Each session has its own unique ID.

 

All sessions can be found in the Visitors report of the Finteza panel. Click any event, go to the Flow section and hover the cursor over a visit. The session ID will appear to the left of the date.

ip #

string

Visitor IP address.

 

Possible values can be found in the Visitors report of the Finteza panel.

ip_organization #

string

Internet provider.

 

Possible values can be found in the Visitors report of the Finteza panel.

ip_flags #

integer

IP address flags:

  • 1– address is TOR output node
  • 2 – address is a proxy server
  • 4 – address is a VPN server
  • 16 – address belongs to a data center
  • 32 – address belongs to a spammer or was involved in an attack on mail systems
  • 64 – address was involved in an attack on SSH servers or password brute-forcing
  • 128 – address was involved in an attack on websites
  • 256 – address was involved in an attack on applications
  • 512 – address belongs to a botnet
  • 1024 – search engine, social network or messenger bot
  • 2048 – blacklisted address

These flags are automatically assigned to IP addresses based on Finteza internal algorithms.

qstatus #

integer

Traffic status:

  • 0 – clean traffic from real users
  • 1 – suspicious traffic: proxy, VPN, Tor nodes, etc.
  • 2 – unwanted traffic: visits from spam IP addresses or hackers, as well as those trying to falsify request parameters and cookies
  • 3 – harmless service traffic generated by search engine, social network and messenger bots
  • 4 – server error during processing

qreason #

integer

Additional traffic parameters:

  • 0 – clean traffic from real users
  • 1 – invalid request method
  • 2 – invalid request signature
  • 3 – Referer HTTP header changed in a request (spoofing)
  • 4 – cookie parameter changed
  • 100 – address is TOR output node
  • 101 – address is a proxy server
  • 102 – address is a VPN server
  • 103 – address belongs to a data center
  • 104 – address was involved in an attack on SSH servers or password brute-forcing
  • 105 – address belongs to a spammer or was involved in an attack on mail systems
  • 106 – address belongs to a botnet
  • 107 – blacklisted address
  • 108 – search engine, social network or messenger bot

UTM and reference parameters #

Grouping

Type

Description

utm_source #

 

source_utm_source #

 

internal_utm_source #

string

Traffic source from the appropriate UTM label of the link.

 

Three separate groupings are available: for the direct visit label, primary source and internal transition.

 

Website or application are usually specified in such labels.

 

Possible label values can be found in the Sources\UTM website report of the Finteza panel.

utm_campaign #

 

source_utm_campaign #

 

internal_utm_campaign #

string

Advertising campaign from the appropriate UTM label of the link.

 

Three separate groupings are available: for the direct visit label, primary source and internal transition.

 

Possible label values can be found in the Sources\UTM website report of the Finteza panel.

utm_medium #

 

source_utm_medium #

 

internal_utm_medium #

string

Advertisement type from the appropriate UTM label of the link.

 

For example, display is a banner ad, cpc is a paid ad, etc.

 

Three separate groupings are available: for the direct visit label, primary source and internal transition.

 

Possible label values can be found in the Sources\UTM website report of the Finteza panel.

utm_term #

 

source_utm_term #

 

internal_utm_term #

string

Additional description.

 

Three separate groupings are available: for the direct visit label, primary source and internal transition.

 

A key word, audience description or a banner group name are usually specified in utm_term labels.

 

Possible label values can be found in the Sources\UTM website report of the Finteza panel.

utm_content #

 

source_utm_content #

 

internal_utm_content #

string

Creative's description or ID from the appropriate UTM label of the link.

 

Three separate groupings are available: for the direct visit label, primary source and internal transition.

 

Possible label values can be found in the Sources\UTM website report of the Finteza panel.

affiliate_s1 – affiliate_s16 #

 

source_s1 – source_s16 #

string

Additional parameters of the links sent by some referrals for advanced traffic labeling.

 

For example, apart from standard UTM labels, a sent link may also contain: www.abc.com?utm_campaign=campaign&s1=customtrack1&s2=customtrack2. customtrack1 and customtrack2 values allow you to arrange requested data.

 

Two types of groupings are available: 16 for direct visit (affiliate_s*) parameters and 16 for a primary source (source_s*).

 

The list of available parameters depends on each referral. For example, you can customize these parameters in Google Adwords.

Other #

Grouping

Type

Description

day #

filetime

Day in Windows FILETIME format.

day_unixtime #

unixtime

Day as the number of seconds since 1970.01.01, for example, day=1549027860.

search_keyword #

string

User's search query (phrase) that resulted in visiting the website.

 

Specified only in requests, in which search engines (request_source_type) are used as sources.

Traffic source and primary source

Sources and primary sources of traffic are different concepts in Finteza:

  • A source is a web page or a resource a user was located at just before making a request to your website (before sending the track to Finteza). request_*, utm_* and affiliate_s* groupings are provided for it.
  • A primary source is a web page or a resource, from which a user originally visited your website. source_*, source_utm* and source_s* groupings are provided for it.

For example, a user comes to your website from a search engine. During the initial visit, a source and primary source are the same. Next, the user goes to another website section and an event with the appropriate attributes is sent to Finteza: now, your website is considered a source (internal transition), while the search engine remains the primary source.

When grouping by source type, this will look as follows:

  • The initial visit via the search engine: request_source_type=3 and source_type=3. The search engine is specified in both traffic source parameters.
  • Subsequent transitions within the website: request_source_type=5 and source_type=3. A new request_source_type (an actual type of the page a user came from) is specified in each subsequent request. source_type remains unchanged for it for a certain period of time. This allows tracking the actual traffic source.

Work with utm_* and source_utm_* is conducted in a similar way. The former ones feature labels from the link used for the transition. The latter ones set the labels, with which the user originally came to the website.

Besides, there are separate sets of groupings for internal transition labels – internal_utm_*. They feature labels from links located on your website.