Management API - Segment Developer Guide

This document explains how to use the Management API to access Segment data.


A Segment is a top level entity in the Management API. It has no parent and no children.

  • Read the entity overview in the Management API overview guide to understand how segments relate to other Management API entities.
  • Read the Accounts & Views (Profiles) conceptual guide for general information about segments.

Google Analytics provides built-in segments, but users can also create and save their own custom segments through the Analytics web interface. An important use of segments is to separate out a subset of sessions when retrieving data from the Core Reporting API.

Before You Begin

This guide demonstrates how to access the Google Analytics API using the following programming languages:
  • Java
  • Python
  • PHP

  • Read the client libraries page for a complete list of programming language specific client libraries that work with the Management API.
  • Read the Reference Guide to access the API without a client library

Each client library provides a single Analytics service object to access all Management API data. To create the service object you generally have to go through the following steps:

  1. Register your application in the Google Developers Console.
  2. Authorize access to Google Analytics data.
  3. Create an Analytics service object.

If you haven't completed these steps, please stop and read the Hello Google Analytics API Tutorial. This tutorial will walk you through the initial steps of building a Google Analytics API application. Once complete, you will be able to use this guide to perform real-world tasks.

The following code snippet continues from step 3: Create an Analytics service object and contains a variable to store an authorized service object.


Analytics analytics = // Read Hello Analytics Tutorial for details.


analytics = # Read Hello Analytics Tutorial for details.


$client = // Read Hello Analytics Tutorial for details.

// Return results as objects.

$analytics = new apiAnalyticsService($client);

The PHP library will return all the API results as an associative array. To return real objects instead, you can call the client useObject method as demonstrated in the example above.

Once you create an Analytics service object, you are ready to make requests to the Management API.

Note: The same Analytics service object can also be used to access the Core Reporting API.


The Management API allows you to list all the segments for an authorized user. To list segments, you first need to create a service object to work with the API.

Listing a User's Segments

The list method on Segments provides access to both the default and custom segments available to the authenticated user. The sample application requests a list of a user's default and custom segments by calling the Segments list method on the Analytics service object by using the following code.


try {
  Segments segments = analytics.management().segments().list().execute();

} catch (GoogleJsonResponseException e) {
  System.err.println("There was a service error: "
      + e.getDetails().getCode() + " : "
      + e.getDetails().getMessage());


  profiles = analytics.management().segments().list().execute()

except TypeError, error:
  # Handle errors in constructing a query.
  print ('There was an error in constructing your query : %s' % error)

except HttpError, error:
  # Handle API errors.
  print ('Arg, there was an API error : %s : %s' %
         (error.resp.status, error._get_reason()))


try {
  $segments = $analytics->management_segments

} catch (apiServiceException $e) {
  print 'There was an Analytics API service error '
  . $e->getCode() . ':' . $e->getMessage();

} catch (apiException $e) {
  print 'There was a general API error '
    . $e->getCode() . ':' . $e->getMessage();
  • If the query was successful, the API will return a 200 status code along with the requested data.
  • If there was an error, the API will return with status code other than 200, as well as a descriptive message describing what caused the error. Read the Error Response section in the reference guide for a full list of all the status codes and what they mean.

The results of the list method are in the segments object. The following code shows how to iterate through the results. For a list of all the properties of a Segment resource, see Segments.


for (Segment segment : segments.getItems()) {
  System.out.println("Segment ID: " + segment.getId());
  System.out.println("Segment Name: " + segment.getName());
  System.out.println("Segment Definition: " + segment.getDefinition());

  // These fields are only set for custom segments and not default segments.
  if (segment.getCreated() != null) {
    System.out.println("Segment Created: " + segment.getCreated());
    System.out.println("Segment Updated: " + segment.getUpdated());


for segment in segments_response.get('items', []):
  print 'Segment ID = %s' % segment.get('id')
  print 'Kind       = %s' % segment.get('kind')
  print 'Self Link  = %s' % segment.get('selfLink')
  print 'Name       = %s' % segment.get('name')
  print 'Definition = %s' % segment.get('definition')

  # These fields are only set for custom segments and not default segments.
  if segment.get('created'):
    print 'Created    = %s' % segment.get('created')
    print 'Updated    = %s' % segment.get('updated')


$html = '';

$items = $segments->getItems();

if (count($items) != 0) {
  foreach ($items as &$segment) {
    $html .= <<<HTML

Segment ID = {$segment->getId()}
Kind       = {$segment->getKind()}
Self Link  = {$segment->getSelfLink()}
Name       = {$segment->getName()}
Definition = {$segment->getDefinition()}
Created    = {$segment->getCreated()}
Updated    = {$segment->getUpdated()}

print $html;

Segments are explained in Segments (Help Center). In a real application, use the value returned in the id property as the segment parameter to the Core Reporting API. All negative ID values are built-in segments while all positive values are custom segments defined for the authenticated user.