Segmentation in the API

Learn how to use the powerful segmentation feature available in Piwik. This page explains how to build the 'segment' parameter in your API requests. Segmentation makes it easy to request any Piwik 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:

http://piwik.example.org/index.php
?token_auth=yourTokenHere
&format=xml
&date=2011-01-11
&period=week
&idSite=1
&module=API&method=Referrers.getKeywords
&segment=browserCode==FF;country==DE

Example URL of top countries used by visits landing on the page: virtual-drums.com/: demo.piwik.org/?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

== Equals &segment=country==IN Return results where the country is India
!= Does not equal &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=@piwik Return results where the Referer name (website domain or search engine name) contains the word "piwik".
!@ Does not contain &segment=referrerKeyword!@yourBrand Return results where the keyword used to access the website does not contain word "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.

Examples

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

AND operator is the ; (semi-colon) character.

Examples

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

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

List of segments

Dimensions

Visit Location
city City
Example values: Sydney, Sao Paolo, Rome, etc.
continentCode Continent
Example values: eur, asi, amc, amn, ams, afr, ant, oce
countryCode Country
Example values: de, us, fr, in, es, 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.
provider Provider
Example values: comcast.net, proxad.net, etc.
regionCode Region
Example values: 01 02, OR, P8, etc.
eg. region=A1;country=fr
Visit
browserCode Browser
Example values: FF, IE, CH, SF, OP, etc.
browserVersion Browser version
Example values: 1.0, 8.0, etc.
deviceType Device type
Example values: desktop, smartphone, tablet, feature phone, console, tv, car browser, smart display, camera
visitLocalHour Local time
Example values: 0, 1, 2, 3, ..., 20, 21, 22, 23
operatingSystemCode Operating system
Example values: WXP, WI7, MAC, LIN, AND, IPD, etc.
resolution Resolution
Example values: 1280x1024, 800x600, etc.
visitServerHour Server time
Example values: 0, 1, 2, 3, ..., 20, 21, 22, 23
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.
visitConverted Visit converted at least one Goal
Example values: 0, 1
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()
visitorType Visitor 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"
Referrers
referrerKeyword Keyword
Example values: Encoded%20Keyword, keyword
referrerName Referrer Name
Example values: twitter.com, www.facebook.com, Bing, Google, Yahoo, CampaignName
referrerType Referrer Type
Example values: direct, search, website, campaign
referrerUrl Referrer URL
Example values: http%3A%2F%2Fwww.example.org%2Freferer-page.htm
Events
eventAction Event Action
eventCategory Event Category
eventName Event Name
Custom Variables
customVariableName1 Custom Variable name 1 (scope visit)
customVariableName2 Custom Variable name 2 (scope visit)
customVariablePageName1 Custom Variable name 1 (scope page)
customVariablePageValue1 Custom Variable value 1 (scope page)
customVariableValue1 Custom Variable value 1 (scope visit)
customVariableValue2 Custom Variable value 2 (scope visit)
There are 5 custom variables available, so you can segment across any segment name and value range.
For example, customVariableName1==Type;customVariableValue1==Customer
Returns all visitors that have the Custom Variable "Type" set to "Customer".
Custom Variables of scope "page" can be queried separately. For example, to query the Custom Variable of scope "page",
stored in index 1, you would use the segment customVariablePageName1==ArticleLanguage;customVariablePageValue1==FR
Actions
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"
entryPageUrl Entry Page URL
entryPageTitle Entry Page title
exitPageTitle Exit Page Title
exitPageUrl Exit Page URL
contentInteraction Interaction
Example values: The type of interaction with the content. For instance "click" or "submit".
siteSearchKeyword Keyword (Site Search)
pageTitle Page Name
pageUrl Page URL
Example values: All these segments must be URL encoded, for example: http%3A%2F%2Fexample.com%2Fpath%2Fpage%3Fquery

Metrics
Visit
daysSinceFirstVisit Days since first visit
daysSinceLastEcommerceOrder Days since last Ecommerce order
daysSinceLastVisit Days since last visit
actions Number of Actions
searches Number of Internal Searches
Example values: To select all visits who used internal Site Search, use: &segment=searches>0
visitCount Number of visits
events Total events
Example values: To select all visits who triggered an Event, use: &segment=events>0
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

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 !=