Skip to Content
APISegmentation

Segmentation

Filter API results to specific subsets of your visitors.

Overview

Segmentation allows you to filter any API report to a subset of your audience. For example, you can request page views only for visitors from a specific country, or conversions only from mobile devices.

Add the segment parameter to any API request to filter results.

Basic Syntax

The segment parameter uses this format:

&segment=dimension==value

Example — visitors from the United States:

&segment=countryCode==US

Operators

OperatorMeaningExample
==EqualscountryCode==US
!=Not equalscountryCode!=US
<=Less than or equalactions<=5
<Less thanactions<5
>=Greater than or equalvisitDuration>=600
>Greater thanvisitDuration>600
=@ContainspageUrl=@/blog/
!@Does not containpageUrl!@/admin/
=^Starts withpageUrl=^https://example.com/services
=$Ends withpageUrl=$/contact

Combining Segments

AND Logic

Use semicolon (;) to combine conditions with AND:

&segment=countryCode==US;browserCode==FF

This returns visitors from the US AND using Firefox.

OR Logic

Use comma (,) to combine conditions with OR:

&segment=countryCode==US,countryCode==CA

This returns visitors from the US OR Canada.

Combined AND/OR

OR takes precedence over AND:

&segment=browserCode==FF;countryCode==US,countryCode==CA

This returns: Firefox users AND (US OR Canada)

To be explicit: (browserCode==FF) AND (countryCode==US OR countryCode==CA)

URL Encoding

Segment values must be URL encoded. Special characters need encoding:

CharacterEncoded
Space%20
/%2F
=%3D
&%26
,%2C
;%3B

Example — page URL containing “/blog/my post”:

&segment=pageUrl=@%2Fblog%2Fmy%20post

Empty/Not Empty Values

Value is empty (is null)

Leave the value blank after ==:

&segment=referrerKeyword==

Returns visitors with no referrer keyword.

Value is not empty (is not null)

Leave the value blank after !=:

&segment=city!=

Returns visitors where city is set.

Common Segments

Visitor Attributes

SegmentDescriptionExample
countryCodeCountry (ISO code)countryCode==US
regionCodeRegion/stateregionCode==CA
cityCity namecity==New%20York
browserCodeBrowserbrowserCode==FF
operatingSystemCodeOSoperatingSystemCode==WIN
deviceTypeDevice typedeviceType==smartphone
resolutionScreen resolutionresolution==1920x1080
browserLangBrowser languagebrowserLang=@en

Visit Attributes

SegmentDescriptionExample
visitDurationVisit length (seconds)visitDuration>=300
actionsActions per visitactions>=5
visitorTypeNew or returningvisitorType==returning
daysSinceFirstVisitDays since first visitdaysSinceFirstVisit>30
daysSinceLastVisitDays since last visitdaysSinceLastVisit<=7
visitCountNumber of visitsvisitCount>=3

Traffic Sources

SegmentDescriptionExample
referrerTypeReferrer typereferrerType==search
referrerNameReferrer namereferrerName==Google
referrerKeywordSearch keywordreferrerKeyword=@matomo
referrerUrlReferrer URLreferrerUrl=@facebook.com

Referrer types: direct, search, website, campaign, social

Campaigns (UTM)

SegmentDescriptionExample
campaignNameutm_campaigncampaignName==spring_sale
campaignSourceutm_sourcecampaignSource==google
campaignMediumutm_mediumcampaignMedium==cpc
campaignContentutm_contentcampaignContent==banner_a
campaignKeywordutm_termcampaignKeyword==analytics

Page/Action

SegmentDescriptionExample
pageUrlPage URLpageUrl=@/services/
pageTitlePage titlepageTitle=@Contact
entryPageUrlEntry page URLentryPageUrl==https://example.com/
exitPageUrlExit page URLexitPageUrl=@/thank-you
siteSearchKeywordSite search querysiteSearchKeyword=@pricing
downloadUrlDownloaded filedownloadUrl=@.pdf
outlinkUrlOutbound link clickedoutlinkUrl=@partner.com

Events

SegmentDescriptionExample
eventCategoryEvent categoryeventCategory==Forms
eventActionEvent actioneventAction==Submit
eventNameEvent nameeventName==Contact%20Form
eventValueEvent valueeventValue>=100

Goals

SegmentDescriptionExample
visitConvertedGoalIdConverted goal IDvisitConvertedGoalId==1
goalConversionPageUrlPage where goal convertedgoalConversionPageUrl=@/thank-you

Complete Examples

Mobile visitors from US with 3+ page views

&segment=deviceType==smartphone;countryCode==US;actions>=3
&segment=visitorType==returning;referrerType==search;referrerName==Google

Visitors who viewed blog but didn’t convert

&segment=pageUrl=@/blog/;visitConvertedGoalId==

Campaign visitors on desktop with long visits

&segment=referrerType==campaign;deviceType==desktop;visitDuration>=300

Visitors from email campaign who completed a form

&segment=campaignMedium==email;eventCategory==Forms;eventAction==Submit

Full API Request Example

Get page views for mobile visitors from the US:

https://example.ghostmetrics.cloud/?module=API
  &method=Actions.getPageUrls
  &idSite=1
  &period=month
  &date=today
  &format=JSON
  &segment=deviceType==smartphone;countryCode==US
  &token_auth=YOUR_TOKEN

Getting Available Segments

To get a list of all available segments for your site:

https://example.ghostmetrics.cloud/?module=API
  &method=API.getSegmentsMetadata
  &idSites=1
  &format=JSON
  &token_auth=YOUR_TOKEN

This returns all segment names, accepted values, and documentation.

Performance Considerations

  • Segments add processing time to API requests
  • Complex segments with many conditions take longer
  • Using segments on large date ranges may be slow
  • Pre-defined segments (saved in Ghost Metrics) may be cached for better performance

Troubleshooting

No data returned

  • Verify segment syntax is correct
  • Check that segment values are URL encoded
  • Confirm the dimension has data (e.g., campaign segments need campaign traffic)
  • Try a simpler segment first

Unexpected results

  • Check operator precedence (OR before AND)
  • Verify case sensitivity (some segments are case-sensitive)
  • Ensure values match exactly (use =@ for partial matches)

Segment not recognized

  • Check spelling of segment name
  • Use API.getSegmentsMetadata to get valid segment names
  • Some segments require specific plugins to be enabled

Next Steps

Last updated on
Parameters ReferenceCommon API Methods