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.).
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
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.
| == | Equals | &segment=country==INReturn results where the country is India |
| != | Does not equal | &segment=actions!=1Return results where the number of actions (page views, downloads, etc.) is not 1 |
| <= | Less than or equal to | &segment=actions<=4Return results where the number of actions (page views, downloads, etc.) is 4 or less |
| < | Less than | &segment=visitServerHour<12Return results where the Server time (hour) is before midday. |
| >= | Greater than or equal to | &segment=visitDuration>=600Return results where visitors spent 10 minutes or more on the website. |
| > | Greater than | &segment=daysSinceLastVisit>1Return results where visitors are coming back to the website 2 days or more after their previous visit. |
| =@ | Contains | &segment=referrerName=@piwikReturn results where the Referer name (website domain or search engine name) contains the word “piwik”. |
| !@ | Does not contain | &segment=referrerKeyword!@yourBrandReturn results where the keyword used to access the website does not contain word “yourBrand”. |
You can combine several segments together with AND and OR logic.
OR operator is the , (comma) character.
Examples
&segment=country==US,country==DECountry is either (United States OR Germany) |
AND operator is the ; (semi-colon) character.
Examples
&segment=visitorType==returning;country==FRReturning visitors AND Country is France |
&segment=referrerType==search;referrerKeyword!=PiwikVisitors 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)”
| 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. |
| 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. |
| Visit | |
| browserCode | Browser Example values: FF, IE, CH, SF, OP, etc. |
| browserVersion | Browser version Example values: 1.0, 8.0, etc. |
| 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 |
| 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" |
| 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 Example values: 34c31e04394bdc63 - any 16 Hexadecimal chars ID, which can be fetched using the Tracking API function getVisitorId() |
| visitIp | Visitor IP Note: This segment can only be used by an Admin user Example values: 13.54.122.1, etc. |
| 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 |
| 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 | |
| entryPageUrl | Entry Page URL |
| entryPageTitle | Entry Page title |
| exitPageTitle | Exit Page Title |
| exitPageUrl | Exit Page URL |
| 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 |
| 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 |
| visitDuration | Visit Duration (in seconds) |
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 !=
English
Feedback on this page
Have you found an error in this page, or do you think some information is missing or not clear? We appreciate you taking the time to send us your suggestions and feedback on this page.