Legacy Google+ APIs have been shut down as of March 7, 2019. Changes to the shutdown plan have been made recently which may mitigate its effect on some developers. Learn more.

Google+ integrations for web and mobile apps have also stopped functioning as of March 7, 2019. Learn more.

Listing circles

The Google+ Domains API allows your app to list all of the circles for a user within your Google Apps domain and to fetch a specific circle. Listing circles is often useful for other domain operations, such as when you need to get the ID of a particular circle prior to adding people to a circle.

To retrieve a circle or a list of circles, your app must request the following scopes:

https://www.googleapis.com/auth/plus.me
Grants the app permission to use the special value me to represent the authenticated user. Does not apply to apps that use domain-wide delegation of authority.
https://www.googleapis.com/auth/plus.circles.read
Required - Grants the app permission to read the names of the user's circles, and the people and pages that are members of each circle.

Listing the circles for a user

The following example demonstrates how to fetch a list of all of the circles for an authenticated user within your Google Apps domain.

Java

// This sample assumes a client object `plusDomains` has been created
// and that the user you want to retrieve a list of circles for is an
// authenticated user.
// To learn more about creating a client, see the OAuth 2.0 example:
//  https://developers.google.com/+/domains/authentication/

import java.util.List;
import com.google.api.services.plusDomains.model.Circle;
import com.google.api.services.plusDomains.model.CircleFeed;

PlusDomains.Circles.List listCircles = plusDomains.circles().list("me");
listCircles.setMaxResults(5L);
CircleFeed circleFeed = listCircles.execute();
List<Circle> circles = circleFeed.getItems();

// Loop until no additional pages of results are available.
while (circles != null) {
  for (Circle circle : circles) {
    System.out.println(circle.getDisplayName());
  }

  // When the next page token is null, there are no additional pages of
  // results. If this is the case, break.
  if (circleFeed.getNextPageToken() != null) {
    // Prepare the next page of results
    listCircles.setPageToken(circleFeed.getNextPageToken());

    // Execute and process the next page request
    circleFeed = listCircles.execute();
    circles = circleFeed.getItems();
  } else {
    circles = null;
  }
}

Python

# This sample assumes a client object `service` has been created and
# that the user you want to retrieve a list of circles for is an
# authenticated user.
# To learn more about creating a client, see the OAuth 2.0 example:
#  https://developers.google.com/+/domains/authentication/

circle_service = service.circles()
request = circle_service.list(userId='me')

while request is not None:
  circle_list = request.execute()

  if circle_list.get('items') is not None:
    print 'Google+ circles for the current user: '
    circles = circle_list.get('items')
    for circle in circles:
      print '\t %s' % circle.get('displayName')

  request = circle_service.list_next(request, circle_list)

Getting a circle

The following example demonstrates how to fetch a circle from within your Google Apps domain.

Java

// This sample assumes a client object `plusDomains` has been created
// and that you know the ID of the circle you want to get.
// To learn more about creating a client, see the OAuth 2.0 example:
//  https://developers.google.com/+/domains/authentication/

import com.google.api.services.plusDomains.model.Circle;

String circleId = "a1234b";
Circle retrievedCircle = plusDomains.circles().get(circleId).execute();

Python

# This sample assumes a client object `service` has been created and
# that you know the ID of the circle you want to get.
# To learn more about creating a client, see the OAuth 2.0 example:
#  https://developers.google.com/+/domains/authentication/

circle_id = 'a1234b'

result = service.circles().get(circleId=circle_id).execute()
print 'Circle retrieved: %s' % result.get('displayName')

Send feedback about...

Google+ Domains API
Google+ Domains API