Segmentation in the API

Learn how to use the powerful segmentation feature available in Ghost Metrics. This page explains how to build the 'segment' parameter in your API requests. Segmentation makes it easy to request any Ghost Metrics report for a subset of your audience.

This page explains how to build and use the 'segment' API URL parameter, and you will find the list of all the supported visitor segments (country, entry page, keyword, returning visitor, etc.).

Segment Parameter in the API URL Request

Segmentation can be applied to most API functions. The segment parameter contains the definition of the segment you wish to filter your reports to.

For example, you can request the "Best Keywords" report processed for all visits where "Country is Germany AND Browser is Firefox" by doing the following request:

https://ghostdemo.ghostmetrics.cloud/index.php
?token_auth=yourTokenHere
&format=xml
&date=2024-01-11
&period=week
&idSite=1
&module=API&method=Referrers.getKeywords
&segment=browserCode==FF;countryCode==DE

Example URL of top countries used by visits landing on the page: virtual-drums.com/: ghostdemo.ghostmetrics.cloud/?module=API&method=UserCountry.getCountry&idSite=3&date=yesterday&period=day&format=xml&filter_truncate=5&language=en**&segment=entryPageUrl==http%3A%2F%2Fwww.virtual-drums.com%2F**

Let's take a look at the segment string.

Segment operators

Operator	Behavior	Example
==	Equals	&segment=countryCode==IN Return results where the country is India
!=	Not equals	&segment=actions!=1 Return results where the number of actions (page views, downloads, etc.) is not 1
<=	Less than or equal to	&segment=actions<=4 Return results where the number of actions (page views, downloads, etc.) is 4 or less
<	Less than	&segment=visitServerHour<12 Return results where the Server time (hour) is before midday.
>=	Greater than or equal to	&segment=visitDuration>=600 Return results where visitors spent 10 minutes or more on the website.
>	Greater than	&segment=daysSinceLastVisit>1 Return results where visitors are coming back to the website 2 days or more after their previous visit.
=@	Contains	&segment=referrerName=@ghost Return results where the Referer name (website domain or search engine name) contains the word "ghost".
!@	Does not contain	&segment=referrerKeyword!@yourBrand Return results where the keyword used to access the website does not contain word "yourBrand".
=^	Starts with	&segment=referrerKeyword=^yourBrand Return results where the keyword used to access the website starts with "yourBrand".
=$	Ends with	&segment=referrerKeyword=$yourBrand Return results where the keyword used to access the website ends with "yourBrand".

Combine Segments with AND and OR expressions

You can combine several segments together with AND and OR logic.

OR operator is the , (comma) character, for example:

• &segment=countryCode==US,countryCode==DE Country is either (United States OR Germany)

AND operator is the ; (semi-colon) character, for example:

• &segment=visitorType==returning;countryCode==FR Returning visitors AND Country is France
• &segment=referrerType==search;referrerKeyword!=Ghost Visitors from Search engines AND Keyword is not Ghost

Note that if you combine OR and AND operators, the OR operator will take precedence. For example, the following query &segment=referrerType==search;referrerKeyword==Ghost,referrerKeyword==analytics will select "Visitors from Search engines AND (Keyword is Ghost OR Keyword is analytics)"

List of segments

Dimensions

Segment String	Segment Name
Visitors
browserName	Browser Example values: FireFox, Internet Explorer, Chrome, Safari, Opera etc.
browserCode	Browser code Example values: FF, IE, CH, SF, OP etc.
browserEngine	Browser engine Example values: Trident, WebKit, Presto, Gecko, Blink, etc.
browserVersion	Browser version Example values: 1.0, 8.0, etc.
deviceBrand	Device brand Example values: Apple, Samsung, Google, etc.
deviceModel	Device model Example values: iPad, Nexus 5, Galaxy S5, Fire TV, etc.
deviceType	Device type Example values: desktop, smartphone, tablet, etc.
fingerprint	Fingerprint Note: This segment can only be used by an Admin user Example values: 1eceaa833348b187 - any 16 Hexadecimal chars ID, which can be fetched from API.getLastVisitsDetails
visitLocalHour	Local time — hour (start of visit) Example values: 0, 1, 2, 3, ..., 20, 21, 22, 23
operatingSystemName	Operating system Example values: Windows, Linux, Mac, Android, iOS etc.
operatingSystemCode	Operating system code Example values: WIN, LIN, MAX, AND, IOS etc.
operatingSystemVersion	Operating system version Example values: XP, 7, 2.3, 5.1, ...
profilable	Profilable Example values: 1 for profilable (eg cookies were used), 0 for not profilable (eg no cookies were used)
resolution	Resolution Example values: 1280x1024, 800x600, etc.
visitStartServerHour	Site time — hour (start of visit) Example values: 0, 1, 2, 3, ..., 20, 21, 22, 23
visitServerHour	Site time — hour (time of last action) Example values: 0, 1, 2, 3, ..., 20, 21, 22, 23
visitEndServerDate	Time in UTC — date (time of last action) Example values: 2018-12-31, 2018-03-20, ...
visitEndServerDayOfMonth	Time in UTC — day of month (time of last action) Example values: 0, 1, 2, 3, ..., 29, 30, 31
visitEndServerDayOfWeek	Time in UTC — day of week (time of last action) Example values: 1, 2, 3, 4, 5, 6, 7
visitEndServerDayOfYear	Time in UTC — day of year (time of last action) Example values: 1, 2, 3, 4, ..., 365, 366
visitStartServerMinute	Time in UTC — minute (start of visit) Example values: 0, 1, 2, 3, ..., 56, 57, 58, 59
visitEndServerMinute	Time in UTC — minute (time of last action) Example values: 0, 1, 2, 3, ..., 56, 57, 58, 59
visitEndServerMonth	Time in UTC — month (time of last action) Example values: 1, 2, 3, ..., 11, 12
visitEndServerQuarter	Time in UTC — quarter (time of last action) Example values: 1, 2, 3, 4
visitEndServerSecond	Time in UTC — second (Time of last action) Example values: 0, 1, 2, 3, ..., 58, 59
visitEndServerWeekOfYear	Time in UTC — week of year (time of last action) Example values: 1, 2, 3, 4, ..., 51, 52, 53
visitEndServerYear	Time in UTC — year (time of last action) Example values: 2016, 2017, 2018, ..., 9998, 9999
userId	User ID Note: This segment can only be used by an Admin user Example values: any non empty unique string identifying the user (such as an email address or a username).
visitEcommerceStatus	Visit Ecommerce status at the end of the visit Example values: none, ordered, abandonedCart, orderedThenAbandonedCart. For example, to select all visits that have made an Ecommerce order, the API request would contain &segment=visitEcommerceStatus==ordered,visitEcommerceStatus==orderedThenAbandonedCart
visitId	Visit ID Note: This segment can only be used by an Admin user Example values: Any integer.
visitConvertedGoalId	Visit converted a specific Goal Id Example values: 1, 2, 3, etc.
visitConvertedGoalName	Visit converted a specific Goal Name Example values: myGoal, myOtherGoal, etc.
visitConverted	Visit converted at least one Goal Example values: 0, 1
visitorType	Visit type Example values: new, returning, returningCustomer. For example, to select all visitors who have returned to the website, including those who have bought something in their previous visits, the API request would contain &segment=visitorType==returning,visitorType==returningCustomer
visitorId	Visitor ID Note: This segment can only be used by an Admin user Example values: 34c31e04394bdc63 - any 16 Hexadecimal chars ID, which can be fetched using the Tracking API function getVisitorId()
Visitor location
city	City Example values: Sydney, Sao Paolo, Rome, etc.
continentCode	Continent Example values: eur, asi, amc, amn, ams, afr, ant, oce
countryName	Country Example values: Germany, France, Spain, ...
countryCode	Country code Example values: ISO 3166-1 alpha-2 country codes (de, us, fr, in, es, etc.)
languageCode	Language Example values: de, fr, en-gb, zh-cn, etc.
latitude	Latitude Example values: -33.578, 40.830, etc. You can select visitors within a lat/long range using &segment=lat>X;lat<Y;long>M;long<N.
longitude	Longitude Example values: -70.664, 14.326, etc.
regionCode	Region Example values: 01 02, OR, P8, etc. eg. region=BFC;country=fr
Behaviour
actionType	Action Type Example values: A type of action, such as: pageviews, contents, sitesearches, events, outlinks, downloads
actionUrl	Action URL
siteSearchCategory	Category (Site Search)
outlinkUrl	Clicked Outlink
contentInteraction	Content Interaction Example values: The type of interaction with the content. For instance "click" or "submit".
contentName	Content Name Example values: The name of a content block, for instance "Ad Sale"
contentPiece	Content Piece Example values: The actual content. For instance "ad.jpg" or "My text ad"
contentTarget	Content Target Example values: For instance the URL of a landing page: "http://landingpage.example.com"
downloadUrl	Download URL
entryPageUrl	Entry Page URL
entryPageTitle	Entry Page title
exitPageTitle	Exit Page Title
exitPageUrl	Exit Page URL
siteSearchKeyword	Keyword (Site Search)
siteSearchCount	Keyword count (Site Search)
pageTitle	Page Title
pageUrl	Page URL
actionServerHour	Site time — hour
actionServerMinute	Time in UTC — minute Example values: 0, 1, 2, 3, ..., 56, 57, 58, 59
Events
eventAction	Event Action
eventCategory	Event Category
eventName	Event Name
eventUrl	Event URL Example values: The URL must be URL encoded, for example: http%3A%2F%2Fexample.com%2Fpath%2Fpage%3Fquery
Acquisition
adClickId	Ad Click ID Example values: A unique Click ID which was generated by an ad provider and used by visitors to reach your website.
adProvider	Ad provider Example values: An ad provider that refers visitors to your website with a specific Click ID.
campaignContent	Campaign Content
campaignGroup	Campaign Group
campaignId	Campaign Id
campaignKeyword	Campaign Keyword
campaignMedium	Campaign Medium
campaignName	Campaign Name
campaignPlacement	Campaign Placement
campaignSource	Campaign Source
referrerType	Channel Type Example values: direct, search, website, campaign
referrerKeyword	Keyword Example values: Encoded%20Keyword, keyword
referrerName	Referrer Name Example values: twitter.com, www.facebook.com, Bing, Google, Yahoo, CampaignName
referrerUrl	Referrer URL Example values: http%3A%2F%2Fwww.example.org%2Freferer-page.htm
Ecommerce
productCategory	Product Category
productName	Product Name
productSku	Product SKU
productViewCategory	Viewed Product Category
productViewName	Viewed Product Name
productViewSku	Viewed Product SKU
Forms
form_name	Form Name Example values: Accepts any form name of a currently running form.
Media
media_impression_type	Impressions of media type Example values: Segment visitors who have viewed a page that had this media type on the page, needs to be either 'audio' or 'video'
media_player	Media player Example values: Segment visitors who used a certain media player on your website
media_resource	Media resource URL Example values: Accepts any media resource (audio / video URL)
media_title	Media title Example values: Accepts any title of your media titles
media_plays_type	Plays of media type Example values: Segment visitors who have played a specific media type, needs to be either 'audio' or 'video'

Metrics

Segment String	Segment Name
Visitors
actions	Actions In Visit
daysSinceFirstVisit	Days since first visit
daysSinceLastEcommerceOrder	Days since last Ecommerce order
daysSinceLastVisit	Days since last visit
events	Events Example values: To select all visits who triggered an Event, use: &segment=events>0
visitLocalMinute	Local time — minute (start of visit) Example values: 0, 1, 2, 3, ..., 67, 57, 58, 59
interactions	Number of Interactions Example values: Any positive integer
searches	Number of Internal Searches Example values: To select all visits who used internal Site Search, use: &segment=searches>0
visitCount	Number of visits
secondsSinceFirstVisit	Seconds since first visit
secondsSinceLastEcommerceOrder	Seconds since last Ecommerce order
secondsSinceLastVisit	Seconds since last visit
visitDuration	Visit Duration (in seconds)
visitIp	Visitor IP Note: This segment can only be used by an Admin user Example values: 13.54.122.1. Select IP ranges with notation: visitIp>13.54.122.0;visitIp<13.54.122.255
Events
eventValue	Event value
Ecommerce
orderId	Order ID
revenueOrder	Order Revenue
productPrice	Product Price
revenueAbandonedCart	Revenue Left In Cart
productViewPrice	Viewed Product Price
Forms
form_converted	Form Converted Example values: Accepts either 1 or 0.
form_num_starts	Number of Form Starts Example values: Accepts any number of form starts.
form_num_submissions	Number of Form Submissions Example values: Accepts any number of form submissions.
form_timespent	Spent Time on Form (in ms) Example values: Any number in milliseconds, for example 1000.
Media
media_length	Media length (in seconds) Example values: Segment visitors who watched a video or listened to audio with a certain length. In seconds
media_spent_time	Time spent playing media (in seconds) Example values: Segment for how long a user watched a video or listened to an audio. In seconds
media_time_initial_play	Time to initial media play (in seconds) Example values: Segment for how long it took for a user to start a video. In seconds

Segment values must be URL encoded

The segment value (located after the segment operator) must be URL encoded before being sent to Ghost. For example to select all visitors that visited your website via a Search keyword containing My brand, you need to URL encode the value such as: &segment=referrerKeyword!@My%20brand.

Segment where value is empty / is not empty

You may sometimes want to segment your analytics reports, for all visitors where a given dimension is empty (a value was not set). This is similar to the SQL "is null" clause. To do so, you can leave the value blank after the operator == in the segment string. For example, to select all visitors that did not have any referrer keyword set, you can write: referrerKeyword==

You can combine it with other segments, for example to select all visitors that come from India and did not have any keyword set: referrerKeyword==;countryCode==in

Similarly, you can segment your traffic to select visitors where a particular segment is not empty (a value was set). This is similar to the SQL "is not null" clause. To do so, you can leave the value blank after the operator != in the segment string. For example to select all visitors that come from India and have a City set, you can write: city!=;countryCode==in

Note: Leaving an empty value is supported for the operators == and !==