Search for groups

You can search for groups matching certain attributes with the groups.list method of the Directory API. This method accepts the query parameter which is a search query combining one or more search clauses. Each search clause is made up of three parts:

Field: Group attribute that is searched. For example, name .
Operator: Test that is performed on the data to provide a match. For example, the = operator tests if a text attribute matches a value.
Value: The content of the attribute that is tested. For example, groupName .

Multiple clauses are separated by whitespace and are implicitly joined by an AND operator.

Fields

Field	Value Type	Operators	Description
`email`	string	`=` , `:{PREFIX}*`	The group's email address. Note: This cannot be used with the `memberKey` parameter in the same query.
`name`	string	`=` , `:{PREFIX}*`	The group's display name. Note: This cannot be used with `memberKey` parameter in the same query.
`memberKey`	string	`=` ,	The `memberKey` query parameter returns all groups for which a user or group has a membership. This value can be any of the user's primary or alias email address, a group's primary or alias email address, or a user's unique ID. Note: This cannot be used along with the `email` or `name` parameters in the same query.

Value Types

Value Type	Notes
string	Surround with single quotes `'` if the query contains whitespace. Escape single quotes in queries with `\'` , for example `'Valentine\'s Day'` .

Operators

Operator	Supported Value Types	Notes
`=`	string, boolean, number, date	The field and the value match exactly. For example, `name=contact` matches all groups with the `name` attribute `"contact"` , but not `"contactgroup"` . Supported on most string fields ( see above ).
`:{PREFIX}*`	string	The field starts with the value. For example, a query with `email:support*` matches groups with `email` values of `"supportgroup@"` , and `"support@"` but not `"contactsupport"` . Only supported on a limited set of string fields ( see above ).

Examples

All queries use the groups.list method, which has an HTTP request similar to the following (line breaks included for readability):

GET https://admin.googleapis.com/admin/directory/v1/groups
?domain= primary domain 
&query= query parameters

The query parameters must be URL encoded. For example, the query query=email:support* is URL encoded as query=email%3Asupport* . All examples on this page show unencoded query parameters. Client libraries handle this URL encoding automatically.

Search for a group by display name

 name='contact'

Search for groups matching an email prefix

  email 
 : 
 admin 
 *

Search for all groups of a user

  memberKey 
 = 
 user 
 @company 
 . 
 com

Search for groups with name and email starting with contact

  name 
 : 
 contact 
 * 
  
 email 
 : 
 contact 
 *