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
*
