# Method: projects.locations.corpora.searchAssets

- [HTTP request](https://docs.cloud.google.com/vision-ai/docs/reference/rest/v1/projects.locations.corpora/searchAssets#body.HTTP_TEMPLATE)
- [Path parameters](https://docs.cloud.google.com/vision-ai/docs/reference/rest/v1/projects.locations.corpora/searchAssets#body.PATH_PARAMETERS)
- [Request body](https://docs.cloud.google.com/vision-ai/docs/reference/rest/v1/projects.locations.corpora/searchAssets#body.request_body)
  - [JSON representation](https://docs.cloud.google.com/vision-ai/docs/reference/rest/v1/projects.locations.corpora/searchAssets#body.request_body.SCHEMA_REPRESENTATION)
- [Response body](https://docs.cloud.google.com/vision-ai/docs/reference/rest/v1/projects.locations.corpora/searchAssets#body.response_body)
  - [JSON representation](https://docs.cloud.google.com/vision-ai/docs/reference/rest/v1/projects.locations.corpora/searchAssets#body.SearchAssetsResponse.SCHEMA_REPRESENTATION)
- [Authorization scopes](https://docs.cloud.google.com/vision-ai/docs/reference/rest/v1/projects.locations.corpora/searchAssets#body.aspect)
- [IAM Permissions](https://docs.cloud.google.com/vision-ai/docs/reference/rest/v1/projects.locations.corpora/searchAssets#body.aspect_1)
- [SchemaKeySortingStrategy](https://docs.cloud.google.com/vision-ai/docs/reference/rest/v1/projects.locations.corpora/searchAssets#SchemaKeySortingStrategy)
  - [JSON representation](https://docs.cloud.google.com/vision-ai/docs/reference/rest/v1/projects.locations.corpora/searchAssets#SchemaKeySortingStrategy.SCHEMA_REPRESENTATION)
- [Option](https://docs.cloud.google.com/vision-ai/docs/reference/rest/v1/projects.locations.corpora/searchAssets#Option)
  - [JSON representation](https://docs.cloud.google.com/vision-ai/docs/reference/rest/v1/projects.locations.corpora/searchAssets#Option.SCHEMA_REPRESENTATION)
- [AggregateMethod](https://docs.cloud.google.com/vision-ai/docs/reference/rest/v1/projects.locations.corpora/searchAssets#AggregateMethod)
- [FacetGroup](https://docs.cloud.google.com/vision-ai/docs/reference/rest/v1/projects.locations.corpora/searchAssets#FacetGroup)
  - [JSON representation](https://docs.cloud.google.com/vision-ai/docs/reference/rest/v1/projects.locations.corpora/searchAssets#FacetGroup.SCHEMA_REPRESENTATION)
- [FacetBucket](https://docs.cloud.google.com/vision-ai/docs/reference/rest/v1/projects.locations.corpora/searchAssets#FacetBucket)
  - [JSON representation](https://docs.cloud.google.com/vision-ai/docs/reference/rest/v1/projects.locations.corpora/searchAssets#FacetBucket.SCHEMA_REPRESENTATION)
- [Range](https://docs.cloud.google.com/vision-ai/docs/reference/rest/v1/projects.locations.corpora/searchAssets#Range)
  - [JSON representation](https://docs.cloud.google.com/vision-ai/docs/reference/rest/v1/projects.locations.corpora/searchAssets#Range.SCHEMA_REPRESENTATION)

Search media asset.

### HTTP request

`POST https://visionai.googleapis.com/v1/{corpus=projects/*/locations/*/corpora/*}:searchAssets`

The URL uses [gRPC Transcoding](https://google.aip.dev/127) syntax.

### Path parameters

| Parameters ||
|---|---|
| `corpus` | `string` Required. The parent corpus to search. Format: \`projects/{projectId}/locations/{locationId}/corpora/{corpus_id}' |

### Request body

The request body contains data with the following structure:

| JSON representation |
|---|
| ``` { "pageSize": integer, "pageToken": string, "contentTimeRanges": { object (`https://docs.cloud.google.com/vision-ai/docs/reference/rest/v1/DateTimeRangeArray`) }, "criteria": [ { object (`https://docs.cloud.google.com/vision-ai/docs/reference/rest/v1/Criteria`) } ], "exclusionCriteria": [ { object (`https://docs.cloud.google.com/vision-ai/docs/reference/rest/v1/Criteria`) } ], "facetSelections": [ { object (`https://docs.cloud.google.com/vision-ai/docs/reference/rest/v1/projects.locations.corpora/searchAssets#FacetGroup`) } ], "resultAnnotationKeys": [ string ], "searchQuery": string, // Union field `sort_spec` can be only one of the following: "schemaKeySortingStrategy": { object (`https://docs.cloud.google.com/vision-ai/docs/reference/rest/v1/projects.locations.corpora/searchAssets#SchemaKeySortingStrategy`) } // End of list of possible types for union field `sort_spec`. } ``` |

| Fields ||
|---|---|
| `pageSize` | `integer` The number of results to be returned in this page. If it's 0, the server will decide the appropriate pageSize. |
| `pageToken` | `string` The continuation token to fetch the next page. If empty, it means it is fetching the first page. |
| `contentTimeRanges` | ``object (`https://docs.cloud.google.com/vision-ai/docs/reference/rest/v1/DateTimeRangeArray`)`` Time ranges that matching video content must fall within. If no ranges are provided, there will be no time restriction. This field is treated just like the criteria below, but defined separately for convenience as it is used frequently. Note that if the endTime is in the future, it will be clamped to the time the request was received. |
| `criteria[]` | ``object (`https://docs.cloud.google.com/vision-ai/docs/reference/rest/v1/Criteria`)`` Criteria applied to search results. |
| `exclusionCriteria[]` | ``object (`https://docs.cloud.google.com/vision-ai/docs/reference/rest/v1/Criteria`)`` Criteria to exclude from search results. Note that `fetchMatchedAnnotations` will be ignored. |
| `facetSelections[]` | ``object (`https://docs.cloud.google.com/vision-ai/docs/reference/rest/v1/projects.locations.corpora/searchAssets#FacetGroup`)`` Stores most recent facet selection state. Only facet groups with user's selection will be presented here. Selection state is either selected or unselected. Only selected facet buckets will be used as search criteria. |
| `resultAnnotationKeys[]` | `string` A list of annotation keys to specify the annotations to be retrieved and returned with each search result. Annotation granularity must be GRANULARITY_ASSET_LEVEL and its search strategy must not be NO_SEARCH. |
| `searchQuery` | `string` Global search query. Allows user to search assets without needing to specify which field the value belongs to. |
| Union field `sort_spec`. Sorting specification. If this field is not specified, by default: - STREAM_VIDEO: search results are sorted by the start time. `sort_spec` can be only one of the following: ||
| `schemaKeySortingStrategy` | ``object (`https://docs.cloud.google.com/vision-ai/docs/reference/rest/v1/projects.locations.corpora/searchAssets#SchemaKeySortingStrategy`)`` Sort by the value under the data schema key. |

### Response body

Response message for corpora.searchAssets.

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

| JSON representation |
|---|
| ``` { "searchResultItems": [ { object (`https://docs.cloud.google.com/vision-ai/docs/reference/rest/v1/SearchResultItem`) } ], "nextPageToken": string, "facetResults": [ { object (`https://docs.cloud.google.com/vision-ai/docs/reference/rest/v1/projects.locations.corpora/searchAssets#FacetGroup`) } ] } ``` |

| Fields ||
|---|---|
| `searchResultItems[]` | ``object (`https://docs.cloud.google.com/vision-ai/docs/reference/rest/v1/SearchResultItem`)`` Returned search results. |
| `nextPageToken` | `string` The next-page continuation token. |
| `facetResults[]` | ``object (`https://docs.cloud.google.com/vision-ai/docs/reference/rest/v1/projects.locations.corpora/searchAssets#FacetGroup`)`` Facet search results of a given query, which contains user's already-selected facet values and updated facet search results. |

### Authorization scopes

Requires the following OAuth scope:

- `https://www.googleapis.com/auth/cloud-platform`

For more information, see the [Authentication Overview](https://cloud.google.com/docs/authentication/).

### IAM Permissions

Requires the following [IAM](https://cloud.google.com/iam/docs) permission on the `corpus` resource:

- `visionai.assets.search`

For more information, see the [IAM documentation](https://cloud.google.com/iam/docs).

## SchemaKeySortingStrategy

A strategy to specify how to sort by data schema key.

| JSON representation |
|---|
| ``` { "options": [ { object (`https://docs.cloud.google.com/vision-ai/docs/reference/rest/v1/projects.locations.corpora/searchAssets#Option`) } ] } ``` |

| Fields ||
|---|---|
| `options[]` | ``object (`https://docs.cloud.google.com/vision-ai/docs/reference/rest/v1/projects.locations.corpora/searchAssets#Option`)`` Options in the front have high priority than those in the back. |

## Option

Option for one data schema key.

| JSON representation |
|---|
| ``` { "dataSchemaKey": string, "sortDecreasing": boolean, "aggregateMethod": enum (`https://docs.cloud.google.com/vision-ai/docs/reference/rest/v1/projects.locations.corpora/searchAssets#AggregateMethod`) } ``` |

| Fields ||
|---|---|
| `dataSchemaKey` | `string` The data used to sort. |
| `sortDecreasing` | `boolean` Whether to sort in decreasing order or increasing order. By default, results are sorted in incresing order. |
| `aggregateMethod` | ``enum (`https://docs.cloud.google.com/vision-ai/docs/reference/rest/v1/projects.locations.corpora/searchAssets#AggregateMethod`)`` Aggregate method for the current data schema key. |

## AggregateMethod

When one result has multiple values with the same key, specify which value is used to sort. By default, AGGREGATE_METHOD_LARGEST is used when results are sorted in decreasing order, AGGREGATE_METHOD_SMALLEST is used when results are sorted in incresing order.

| Enums ||
|---|---|
| `AGGREGATE_METHOD_UNSPECIFIED` | The unspecified aggregate method will be overwritten as mentioned above. |
| `AGGREGATE_METHOD_LARGEST` | Take the (lexicographical or numerical) largest value to sort. |
| `AGGREGATE_METHOD_SMALLEST` | Take the (lexicographical or numerical) smallest value to sort. |

## FacetGroup

A group of facet buckets to be passed back and forth between backend \& frontend.

| JSON representation |
|---|
| ``` { "facetId": string, "displayName": string, "buckets": [ { object (`https://docs.cloud.google.com/vision-ai/docs/reference/rest/v1/projects.locations.corpora/searchAssets#FacetBucket`) } ], "bucketType": enum (`https://docs.cloud.google.com/vision-ai/docs/reference/rest/v1/projects.locations.corpora.searchConfigs#FacetBucketType`), "fetchMatchedAnnotations": boolean } ``` |

| Fields ||
|---|---|
| `facetId` | `string` Unique id of the facet group. |
| `displayName` | `string` Display name of the facet. To be used by UI for facet rendering. |
| `buckets[]` | ``object (`https://docs.cloud.google.com/vision-ai/docs/reference/rest/v1/projects.locations.corpora/searchAssets#FacetBucket`)`` Buckets associated with the facet. E.g. for "Team" facet, the bucket can be 49ers, patriots, etc. |
| `bucketType` | ``enum (`https://docs.cloud.google.com/vision-ai/docs/reference/rest/v1/projects.locations.corpora.searchConfigs#FacetBucketType`)`` Facet bucket type. |
| `fetchMatchedAnnotations` | `boolean` If true, return query matched annotations for this facet group's selection. This option is only applicable for facets based on partition level annotations. It supports the following facet values: - INTEGER - STRING (DataSchema.SearchStrategy.EXACT_SEARCH only) |

## FacetBucket

Holds the facet value, selections state, and metadata.

| JSON representation |
|---|
| ``` { "selected": boolean, // Union field `bucket_value` can be only one of the following: "value": { object (`https://docs.cloud.google.com/vision-ai/docs/reference/rest/v1/projects.locations.corpora.searchConfigs#FacetValue`) }, "range": { object (`https://docs.cloud.google.com/vision-ai/docs/reference/rest/v1/projects.locations.corpora/searchAssets#Range`) } // End of list of possible types for union field `bucket_value`. } ``` |

| Fields ||
|---|---|
| `selected` | `boolean` Whether one facet bucket is selected. This field represents user's facet selection. It is set by frontend in SearchVideosRequest. |
| Union field `bucket_value`. Bucket associated with a facet. For example, bucket of facet "team" can be "49ers", "patriots", etc; bucket of facet "player" can be "tom brady", "drew brees", etc. `bucket_value` can be only one of the following: ||
| `value` | ``object (`https://docs.cloud.google.com/vision-ai/docs/reference/rest/v1/projects.locations.corpora.searchConfigs#FacetValue`)`` Singular value. |
| `range` | ``object (`https://docs.cloud.google.com/vision-ai/docs/reference/rest/v1/projects.locations.corpora/searchAssets#Range`)`` Range value. |

## Range

The range of values \[start, end) for which faceting is applied.

| JSON representation |
|---|
| ``` { "start": { object (`https://docs.cloud.google.com/vision-ai/docs/reference/rest/v1/projects.locations.corpora.searchConfigs#FacetValue`) }, "end": { object (`https://docs.cloud.google.com/vision-ai/docs/reference/rest/v1/projects.locations.corpora.searchConfigs#FacetValue`) } } ``` |

| Fields ||
|---|---|
| `start` | ``object (`https://docs.cloud.google.com/vision-ai/docs/reference/rest/v1/projects.locations.corpora.searchConfigs#FacetValue`)`` Start of the range. Non-existence indicates some bound (e.g. -inf). |
| `end` | ``object (`https://docs.cloud.google.com/vision-ai/docs/reference/rest/v1/projects.locations.corpora.searchConfigs#FacetValue`)`` End of the range. Non-existence indicates some bound (e.g. inf). |