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*