Method: query.search

The Cloud Search Query API provides the search method, which returns the most relevant results from a user query. The results can come from Google Workspace apps, such as Gmail or Google Drive, or they can come from data that you have indexed from a third party.

Note: This API requires a standard end user account to execute. A service account can't perform Query API requests directly; to use a service account to perform queries, set up Google Workspace domain-wide delegation of authority.

HTTP request

POST https://cloudsearch.googleapis.com/v1/query/search

The URL uses gRPC Transcoding syntax.

Request body

The request body contains data with the following structure:

JSON representation 
{
  "requestOptions": {
    object (RequestOptions)
  },
  "query": string,
  "pageSize": integer,
  "start": integer,
  "dataSourceRestrictions": [
    {
      object (DataSourceRestriction)
    }
  ],
  "facetOptions": [
    {
      object (FacetOptions)
    }
  ],
  "sortOptions": {
    object (SortOptions)
  },
  "queryInterpretationOptions": {
    object (QueryInterpretationOptions)
  },
  "contextAttributes": [
    {
      object (ContextAttribute)
    }
  ]
}
Fields
requestOptions

object (RequestOptions)

Request options, such as the search application and user timezone.
query

string

The raw query string. See supported search operators in the Narrow your search with operators
pageSize

integer

Maximum number of search results to return in one page. Valid values are between 1 and 100, inclusive. Default value is 10. Minimum value is 50 when results beyond 2000 are requested.
start

integer

Starting index of the results.
dataSourceRestrictions[]

object (DataSourceRestriction)

The sources to use for querying. If not specified, all data sources from the current search application are used.
facetOptions[]

object (FacetOptions)
sortOptions

object (SortOptions)

The options for sorting the search results
queryInterpretationOptions

object (QueryInterpretationOptions)

options to interpret the user query.
contextAttributes[]

object (ContextAttribute)

Context attributes for the request which will be used to adjust ranking of search results. The maximum number of elements is 10.

Response body

If successful, the response body contains data with the following structure:

The search API response.

JSON representation 
{
  "queryInterpretation": {
    object (QueryInterpretation)
  },
  "results": [
    {
      object (SearchResult)
    }
  ],
  "structuredResults": [
    {
      object (StructuredResult)
    }
  ],
  "spellResults": [
    {
      object (SpellResult)
    }
  ],
  "facetResults": [
    {
      object (FacetResult)
    }
  ],
  "hasMoreResults": boolean,
  "debugInfo": {
    object (ResponseDebugInfo)
  },
  "errorInfo": {
    object (ErrorInfo)
  },
  "resultCounts": {
    object (ResultCounts)
  },

  // Union field result_count can be only one of the following:
  "resultCountEstimate": string,
  "resultCountExact": string
  // End of list of possible types for union field result_count.
}
Fields
queryInterpretation

object (QueryInterpretation)

Query interpretation result for user query. Empty if query interpretation is disabled.
results[]

object (SearchResult)

Results from a search query.
structuredResults[]

object (StructuredResult)

Structured results for the user query. These results are not counted against the pageSize.
spellResults[]

object (SpellResult)

Suggested spelling for the query.
facetResults[]

object (FacetResult)

Repeated facet results.
hasMoreResults

boolean

Whether there are more search results matching the query.
debugInfo

object (ResponseDebugInfo)

Debugging information about the response.
errorInfo

object (ErrorInfo)

Error information about the response.
resultCounts

object (ResultCounts)

Expanded result count information.

Union field result_count. The total result count across all requested data sources. Omitted if predefined sources are included in the set of data sources queried. Result counts might be returned as an estimate, instead of exact, under the following circumstances:

  • When the query has more than 2 terms in a phrase, such as "result count exact" in quotes.

  • When the number of unique search result ACLs to evaluate are too large to compute within a reasonable latency.

In the rare case when the system is unable to search through all documents, rerun the query. result_count can be only one of the following:
resultCountEstimate

string (int64 format)

The estimated result count for this query.
resultCountExact

string (int64 format)

The exact result count for this query.

Authorization Scopes

Requires one of the following OAuth scopes:

  • https://www.googleapis.com/auth/cloud_search.query
  • https://www.googleapis.com/auth/cloud_search

For more information, see the Authorization guide.

QueryInterpretationOptions

options to interpret user query.

JSON representation 
{
  "disableNlInterpretation": boolean,
  "enableVerbatimMode": boolean,
  "disableSupplementalResults": boolean
}
Fields
disableNlInterpretation

boolean

Flag to disable natural language (NL) interpretation of queries. Default is false, Set to true to disable natural language interpretation. NL interpretation only applies to predefined datasources.
enableVerbatimMode

boolean

Enable this flag to turn off all internal optimizations like natural language (NL) interpretation of queries, supplemental result retrieval, and usage of synonyms including custom ones. Nl interpretation will be disabled if either one of the two flags is true.
disableSupplementalResults

boolean

Use this flag to disable supplemental results for a query. Supplemental results setting chosen at SearchApplication level will take precedence if set to True.

QueryInterpretation

JSON representation 
{
  "interpretedQuery": string,
  "interpretationType": enum (QueryInterpretation.InterpretationType),
  "reason": enum (QueryInterpretation.Reason)
}
Fields
interpretedQuery

string

The interpretation of the query used in search. For example, queries with natural language intent like "email from john" will be interpreted as "from:john source:mail". This field will not be filled when the reason is NOT_ENOUGH_RESULTS_FOUND_FOR_USER_QUERY.
interpretationType

enum (QueryInterpretation.InterpretationType)
reason

enum (QueryInterpretation.Reason)

The reason for interpretation of the query. This field will not be UNSPECIFIED if the interpretation type is not NONE.

QueryInterpretation.InterpretationType

Enums
NONE Neither the natural language interpretation, nor a broader version of the query is used to fetch the search results.
BLEND The results from original query are blended with other results. The reason for blending these other results with the results from original query is populated in the 'Reason' field below.
REPLACE The results from original query are replaced. The reason for replacing the results from original query is populated in the 'Reason' field below.

QueryInterpretation.Reason

Enums
UNSPECIFIED
QUERY_HAS_NATURAL_LANGUAGE_INTENT Natural language interpretation of the query is used to fetch the search results.
NOT_ENOUGH_RESULTS_FOUND_FOR_USER_QUERY Query and document terms similarity is used to selectively broaden the query to retrieve additional search results since enough results were not found for the user query. Interpreted query will be empty for this case.

SearchResult

Results containing indexed information for a document.

JSON representation 
{
  "title": string,
  "url": string,
  "snippet": {
    object (Snippet)
  },
  "metadata": {
    object (Metadata)
  },
  "clusteredResults": [
    {
      object (SearchResult)
    }
  ],
  "debugInfo": {
    object (ResultDebugInfo)
  }
}
Fields
title

string

Title of the search result.
url

string

The URL of the search result. The URL contains a Google redirect to the actual item. This URL is signed and shouldn't be changed.
snippet

object (Snippet)

The concatenation of all snippets (summaries) available for this result.
metadata

object (Metadata)

metadata of the search result.
clusteredResults[]

object (SearchResult)

If source is clustered, provide list of clustered results. There will only be one level of clustered results. If current source is not enabled for clustering, this field will be empty.
debugInfo

object (ResultDebugInfo)

Debugging information about this search result.

Snippet

Snippet of the search result, which summarizes the content of the resulting page.

JSON representation 
{
  "snippet": string,
  "matchRanges": [
    {
      object (MatchRange)
    }
  ]
}
Fields
snippet

string

The snippet of the document. The snippet of the document. May contain escaped HTML character that should be unescaped prior to rendering.
matchRanges[]

object (MatchRange)

The matched ranges in the snippet.

MatchRange

Matched range of a snippet [start, end).

JSON representation 
{
  "start": integer,
  "end": integer
}
Fields
start

integer

Starting position of the match in the snippet.
end

integer

End of the match in the snippet.

Metadata

metadata of a matched search result.

JSON representation 
{
  "source": {
    object (Source)
  },
  "mimeType": string,
  "thumbnailUrl": string,
  "owner": {
    object (Person)
  },
  "createTime": string,
  "updateTime": string,
  "fields": [
    {
      object (NamedProperty)
    }
  ],
  "displayOptions": {
    object (ResultDisplayMetadata)
  },
  "objectType": string
}
Fields
source

object (Source)

The named source for the result, such as Gmail.
mimeType

string

Mime type of the search result.
thumbnailUrl

string

The thumbnail URL of the result.
owner

object (Person)

owner (usually creator) of the document or object of the search result.
createTime

string (Timestamp format)

The creation time for this document or object in the search result.

A timestamp in RFC3339 UTC "Zulu" format, with nanosecond resolution and up to nine fractional digits. Examples: "2014-10-02T15:01:23Z" and "2014-10-02T15:01:23.045123456Z".
updateTime

string (Timestamp format)

The last modified date for the object in the search result. If not set in the item, the value returned here is empty. When updateTime is used for calculating freshness and is not set, this value defaults to 2 years from the current time.

A timestamp in RFC3339 UTC "Zulu" format, with nanosecond resolution and up to nine fractional digits. Examples: "2014-10-02T15:01:23Z" and "2014-10-02T15:01:23.045123456Z".
fields[]

object (NamedProperty)

Indexed fields in structured data, returned as a generic named property.
displayOptions

object (ResultDisplayMetadata)

options that specify how to display a structured data search result.
objectType

string

Object type of the search result.

ResultDisplayMetadata

JSON representation 
{
  "objectTypeLabel": string,
  "metalines": [
    {
      object (ResultDisplayMetadata.ResultDisplayLine)
    }
  ]
}
Fields
objectTypeLabel

string

The display label for the object.
metalines[]

object (ResultDisplayMetadata.ResultDisplayLine)

The metalines content to be displayed with the result.

ResultDisplayMetadata.ResultDisplayLine

The collection of fields that make up a displayed line

JSON representation 
{
  "fields": [
    {
      object (ResultDisplayMetadata.ResultDisplayField)
    }
  ]
}
Fields
fields[]

object (ResultDisplayMetadata.ResultDisplayField)

ResultDisplayMetadata.ResultDisplayField

Display Fields for query.search Results

JSON representation 
{
  "label": string,
  "operatorName": string,
  "property": {
    object (NamedProperty)
  }
}
Fields
label

string

The display label for the property.
operatorName

string

The operator name of the property.
property

object (NamedProperty)

The name value pair for the property.

ResultDebugInfo

Debugging information about the result.

JSON representation 
{
  "formattedDebugInfo": string
}
Fields
formattedDebugInfo

string

General debug info formatted for display.

StructuredResult

Structured results that are returned as part of search request.

JSON representation 
{
  "person": {
    object (Person)
  }
}
Fields
person

object (Person)

Representation of a person

SpellResult

JSON representation 
{
  "suggestedQuery": string
}
Fields
suggestedQuery

string

The suggested spelling of the query.

FacetResult

Source specific facet response

JSON representation 
{
  "sourceName": string,
  "objectType": string,
  "operatorName": string,
  "buckets": [
    {
      object (FacetBucket)
    }
  ]
}
Fields
sourceName

string

Source name for which facet results are returned. Will not be empty.
objectType

string

Object type for which facet results are returned. Can be empty.
operatorName

string

The name of the operator chosen for faceting. @see cloudsearch.SchemaPropertyOptions
buckets[]

object (FacetBucket)

FacetBuckets for values in response containing at least a single result with the corresponding filter.

FacetBucket

A bucket in a facet is the basic unit of operation. A bucket can comprise either a single value OR a contiguous range of values, depending on the type of the field bucketed. FacetBucket is currently used only for returning the response object.

JSON representation 
{
  "count": integer,
  "percentage": integer,
  "filter": {
    object (Filter)
  },
  "value": {
    object (Value)
  }
}
Fields
count

integer

Number of results that match the bucket value. Counts are only returned for searches when count accuracy is ensured. Cloud Search does not guarantee facet counts for any query and facet counts might be present only intermittently, even for identical queries. Do not build dependencies on facet count existence; instead use facet ount percentages which are always returned.
percentage

integer

Percent of results that match the bucket value. The returned value is between (0-100], and is rounded down to an integer if fractional. If the value is not explicitly returned, it represents a percentage value that rounds to 0. Percentages are returned for all searches, but are an estimate. Because percentages are always returned, you should render percentages instead of counts.
filter

object (Filter)

Filter to be passed in the search request if the corresponding bucket is selected.
value

object (Value)

ResponseDebugInfo

Debugging information about the response.

JSON representation 
{
  "formattedDebugInfo": string
}
Fields
formattedDebugInfo

string

General debug info formatted for display.

ErrorInfo

Error information about the response.

JSON representation 
{
  "errorMessages": [
    {
      object (ErrorMessage)
    }
  ]
}
Fields
errorMessages[]

object (ErrorMessage)

ErrorMessage

Error message per source response.

JSON representation 
{
  "source": {
    object (Source)
  },
  "errorMessage": string
}
Fields
source

object (Source)
errorMessage

string

ResultCounts

Result count information

JSON representation 
{
  "sourceResultCounts": [
    {
      object (SourceResultCount)
    }
  ]
}
Fields
sourceResultCounts[]

object (SourceResultCount)

Result count information for each source with results.

SourceResultCount

Per source result count information.

JSON representation 
{
  "source": {
    object (Source)
  },
  "hasMoreResults": boolean,

  // Union field result_count can be only one of the following:
  "resultCountEstimate": string,
  "resultCountExact": string
  // End of list of possible types for union field result_count.
}
Fields
source

object (Source)

The source the result count information is associated with.
hasMoreResults

boolean

Whether there are more search results for this source.

Union field result_count.

result_count can be only one of the following:
resultCountEstimate

string (int64 format)

The estimated result count for this source.
resultCountExact

string (int64 format)

The exact result count for this source.