# Method: mediaItems.search

- [HTTP request](https://developers.google.com/photos/library/reference/rest/v1/mediaItems/search#body.HTTP_TEMPLATE)
- [Request body](https://developers.google.com/photos/library/reference/rest/v1/mediaItems/search#body.request_body)
  - [JSON representation](https://developers.google.com/photos/library/reference/rest/v1/mediaItems/search#body.request_body.SCHEMA_REPRESENTATION)
- [Response body](https://developers.google.com/photos/library/reference/rest/v1/mediaItems/search#body.response_body)
  - [JSON representation](https://developers.google.com/photos/library/reference/rest/v1/mediaItems/search#body.SearchMediaItemsResponse.SCHEMA_REPRESENTATION)
- [Authorization scopes](https://developers.google.com/photos/library/reference/rest/v1/mediaItems/search#body.aspect)
- [Filters](https://developers.google.com/photos/library/reference/rest/v1/mediaItems/search#Filters)
  - [JSON representation](https://developers.google.com/photos/library/reference/rest/v1/mediaItems/search#Filters.SCHEMA_REPRESENTATION)
- [DateFilter](https://developers.google.com/photos/library/reference/rest/v1/mediaItems/search#DateFilter)
  - [JSON representation](https://developers.google.com/photos/library/reference/rest/v1/mediaItems/search#DateFilter.SCHEMA_REPRESENTATION)
- [Date](https://developers.google.com/photos/library/reference/rest/v1/mediaItems/search#Date)
  - [JSON representation](https://developers.google.com/photos/library/reference/rest/v1/mediaItems/search#Date.SCHEMA_REPRESENTATION)
- [DateRange](https://developers.google.com/photos/library/reference/rest/v1/mediaItems/search#DateRange)
  - [JSON representation](https://developers.google.com/photos/library/reference/rest/v1/mediaItems/search#DateRange.SCHEMA_REPRESENTATION)
- [ContentFilter](https://developers.google.com/photos/library/reference/rest/v1/mediaItems/search#ContentFilter)
  - [JSON representation](https://developers.google.com/photos/library/reference/rest/v1/mediaItems/search#ContentFilter.SCHEMA_REPRESENTATION)
- [ContentCategory](https://developers.google.com/photos/library/reference/rest/v1/mediaItems/search#ContentCategory)
- [MediaTypeFilter](https://developers.google.com/photos/library/reference/rest/v1/mediaItems/search#MediaTypeFilter)
  - [JSON representation](https://developers.google.com/photos/library/reference/rest/v1/mediaItems/search#MediaTypeFilter.SCHEMA_REPRESENTATION)
- [MediaType](https://developers.google.com/photos/library/reference/rest/v1/mediaItems/search#MediaType)
- [FeatureFilter](https://developers.google.com/photos/library/reference/rest/v1/mediaItems/search#FeatureFilter)
  - [JSON representation](https://developers.google.com/photos/library/reference/rest/v1/mediaItems/search#FeatureFilter.SCHEMA_REPRESENTATION)
- [Feature](https://developers.google.com/photos/library/reference/rest/v1/mediaItems/search#Feature)
- [Try it!](https://developers.google.com/photos/library/reference/rest/v1/mediaItems/search#try-it)

Searches for app created media items in a user's Google Photos library. Only media items and ablums created by your app are returned. If no filters are set, then all app created media items in the user's library are returned. If an app created album is set, all media items in the specified album are returned. If filters are specified, app created media items that match the filters from the user's library are listed. If you set both the album and the filters, the request results in an error.

### HTTP request

`POST https://photoslibrary.googleapis.com/v1/mediaItems:search`

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

### Request body

The request body contains data with the following structure:

| JSON representation |
|---|
| ``` { "albumId": string, "pageSize": integer, "pageToken": string, "filters": { object (`https://developers.google.com/photos/library/reference/rest/v1/mediaItems/search#Filters`) }, "orderBy": string } ``` |

| Fields ||
|---|---|
| `albumId` | `string` Identifier of an album. If populated, lists all media items in specified album. Can't set in conjunction with any filters. |
| `pageSize` | `integer` Maximum number of media items to return in the response. Fewer media items might be returned than the specified number. The default `pageSize` is 25, the maximum is 100. |
| `pageToken` | `string` A continuation token to get the next page of the results. Adding this to the request returns the rows after the `pageToken`. The `pageToken` should be the value returned in the `nextPageToken` parameter in the response to the `searchMediaItems` request. |
| `filters` | ``object (`https://developers.google.com/photos/library/reference/rest/v1/mediaItems/search#Filters`)`` Filters to apply to the request. Can't be set in conjunction with an `albumId`. |
| `orderBy` | `string` An optional field to specify the sort order of the search results. The `orderBy` field only works when a `https://developers.google.com/photos/library/reference/rest/v1/mediaItems/search#DateFilter` is used. When this field is not specified, results are displayed newest first, oldest last by their `https://developers.google.com/photos/library/reference/rest/v1/mediaItems#MediaMetadata.FIELDS.creation_time`. Providing `MediaMetadata.creation_time` displays search results in the opposite order, oldest first then newest last. To display results newest first then oldest last, include the `desc` argument as follows: `MediaMetadata.creation_time desc`. The only additional filters that can be used with this parameter are `https://developers.google.com/photos/library/reference/rest/v1/mediaItems/search#Filters.FIELDS.include_archived_media` and `https://developers.google.com/photos/library/reference/rest/v1/mediaItems/search#Filters.FIELDS.exclude_non_app_created_data`. No other filters are supported. |

### Response body

List of media items that match the search parameters.

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

| JSON representation |
|---|
| ``` { "mediaItems": [ { object (`https://developers.google.com/photos/library/reference/rest/v1/mediaItems#MediaItem`) } ], "nextPageToken": string } ``` |

| Fields ||
|---|---|
| `mediaItems[]` | ``object (`https://developers.google.com/photos/library/reference/rest/v1/mediaItems#MediaItem`)`` Output only. List of media items that match the search parameters. |
| `nextPageToken` | `string` Output only. Use this token to get the next set of media items. Its presence is the only reliable indicator of more media items being available in the next request. |

### Authorization scopes

Requires one of the following OAuth scopes:

- `
  https://www.googleapis.com/auth/photoslibrary.readonly.appcreateddata`

## Filters

Filters that can be applied to a media item search. If multiple filter options are specified, they're treated as AND with each other.

| JSON representation |
|---|
| ``` { "dateFilter": { object (`https://developers.google.com/photos/library/reference/rest/v1/mediaItems/search#DateFilter`) }, "contentFilter": { object (`https://developers.google.com/photos/library/reference/rest/v1/mediaItems/search#ContentFilter`) }, "mediaTypeFilter": { object (`https://developers.google.com/photos/library/reference/rest/v1/mediaItems/search#MediaTypeFilter`) }, "featureFilter": { object (`https://developers.google.com/photos/library/reference/rest/v1/mediaItems/search#FeatureFilter`) }, "includeArchivedMedia": boolean, "excludeNonAppCreatedData": boolean } ``` |

| Fields ||
|---|---|
| `dateFilter` | ``object (`https://developers.google.com/photos/library/reference/rest/v1/mediaItems/search#DateFilter`)`` Filters the media items based on their creation date. |
| `contentFilter` | ``object (`https://developers.google.com/photos/library/reference/rest/v1/mediaItems/search#ContentFilter`)`` Filters the media items based on their content. |
| `mediaTypeFilter` | ``object (`https://developers.google.com/photos/library/reference/rest/v1/mediaItems/search#MediaTypeFilter`)`` Filters the media items based on the type of media. |
| `featureFilter` | ``object (`https://developers.google.com/photos/library/reference/rest/v1/mediaItems/search#FeatureFilter`)`` Filters the media items based on their features. |
| `includeArchivedMedia` | `boolean` If set, the results include media items that the user has archived. Defaults to false (archived media items aren't included). |
| `excludeNonAppCreatedData` | `boolean` If set, the results exclude media items that were not created by this app. Defaults to false (all media items are returned). This field is ignored if the photoslibrary.readonly.appcreateddata scope is used. |

## DateFilter

This filter defines the allowed dates or date ranges for the media returned. It's possible to pick a set of specific dates and a set of date ranges. Media items uploaded without metadata specifying the date the media item was captured will not be returned in queries using date filters. Google Photos server upload time is not used as a fallback in this case.

| JSON representation |
|---|
| ``` { "dates": [ { object (`https://developers.google.com/photos/library/reference/rest/v1/mediaItems/search#Date`) } ], "ranges": [ { object (`https://developers.google.com/photos/library/reference/rest/v1/mediaItems/search#DateRange`) } ] } ``` |

| Fields ||
|---|---|
| `dates[]` | ``object (`https://developers.google.com/photos/library/reference/rest/v1/mediaItems/search#Date`)`` List of dates that match the media items' creation date. A maximum of 5 dates can be included per request. |
| `ranges[]` | ``object (`https://developers.google.com/photos/library/reference/rest/v1/mediaItems/search#DateRange`)`` List of dates ranges that match the media items' creation date. A maximum of 5 dates ranges can be included per request. |

## Date

Represents a whole calendar date. Set `day` to 0 when only the month and year are significant, for example, all of December 2018. Set `day` and `month` to 0 if only the year is significant, for example, the entire of 2018. Set `year` to 0 when only the day and month are significant, for example, an anniversary or birthday.

Unsupported: Setting all values to 0, only `month` to 0, or both `day` and `year` to 0 at the same time.

| JSON representation |
|---|
| ``` { "year": integer, "month": integer, "day": integer } ``` |

| Fields ||
|---|---|
| `year` | `integer` Year of the date. Must be from 1 to 9999, or 0 to specify a date without a year. |
| `month` | `integer` Month of a year. Must be from 1 to 12, or 0 to specify a year without a month and day. |
| `day` | `integer` Day of month. Must be from 1 to 31 and valid for the year and month, or 0 if specifying a year/month where the day isn't significant. |

## DateRange

Defines a range of dates. Both dates must be of the same format. For more information, see `https://developers.google.com/photos/library/reference/rest/v1/mediaItems/search#Date`.

| JSON representation |
|---|
| ``` { "startDate": { object (`https://developers.google.com/photos/library/reference/rest/v1/mediaItems/search#Date`) }, "endDate": { object (`https://developers.google.com/photos/library/reference/rest/v1/mediaItems/search#Date`) } } ``` |

| Fields ||
|---|---|
| `startDate` | ``object (`https://developers.google.com/photos/library/reference/rest/v1/mediaItems/search#Date`)`` The start date (included as part of the range) in one of the formats described. |
| `endDate` | ``object (`https://developers.google.com/photos/library/reference/rest/v1/mediaItems/search#Date`)`` The end date (included as part of the range). It must be specified in the same format as the start date. |

## ContentFilter

This filter allows you to return media items based on the content type.

It's possible to specify a list of categories to include, and/or a list of categories to exclude. Within each list, the categories are combined with an OR.

The content filter `includedContentCategories`: \[c1, c2, c3\] would get media items that contain (c1 OR c2 OR c3).

The content filter `excludedContentCategories`: \[c1, c2, c3\] would NOT get media items that contain (c1 OR c2 OR c3).

You can also include some categories while excluding others, as in this example: `includedContentCategories`: \[c1, c2\], `excludedContentCategories`: \[c3, c4\]

The previous example would get media items that contain (c1 OR c2) AND NOT (c3 OR c4). A category that appears in `includedContentategories` must not appear in `excludedContentCategories`.

| JSON representation |
|---|
| ``` { "includedContentCategories": [ enum (`https://developers.google.com/photos/library/reference/rest/v1/mediaItems/search#ContentCategory`) ], "excludedContentCategories": [ enum (`https://developers.google.com/photos/library/reference/rest/v1/mediaItems/search#ContentCategory`) ] } ``` |

| Fields ||
|---|---|
| `includedContentCategories[]` | ``enum (`https://developers.google.com/photos/library/reference/rest/v1/mediaItems/search#ContentCategory`)`` The set of categories to be included in the media item search results. The items in the set are ORed. There's a maximum of 10 `includedContentCategories` per request. |
| `excludedContentCategories[]` | ``enum (`https://developers.google.com/photos/library/reference/rest/v1/mediaItems/search#ContentCategory`)`` The set of categories which are not to be included in the media item search results. The items in the set are ORed. There's a maximum of 10 `excludedContentCategories` per request. |

## ContentCategory

This is a set of pre-defined content categories that you can filter on.

| Enums ||
|---|---|
| `NONE` | Default content category. This category is ignored when any other category is used in the filter. |
| `LANDSCAPES` | Media items containing landscapes. |
| `RECEIPTS` | Media items containing receipts. |
| `CITYSCAPES` | Media items containing cityscapes. |
| `LANDMARKS` | Media items containing landmarks. |
| `SELFIES` | Media items that are selfies. |
| `PEOPLE` | Media items containing people. |
| `PETS` | Media items containing pets. |
| `WEDDINGS` | Media items from weddings. |
| `BIRTHDAYS` | Media items from birthdays. |
| `DOCUMENTS` | Media items containing documents. |
| `TRAVEL` | Media items taken during travel. |
| `ANIMALS` | Media items containing animals. |
| `FOOD` | Media items containing food. |
| `SPORT` | Media items from sporting events. |
| `NIGHT` | Media items taken at night. |
| `PERFORMANCES` | Media items from performances. |
| `WHITEBOARDS` | Media items containing whiteboards. |
| `SCREENSHOTS` | Media items that are screenshots. |
| `UTILITY` | Media items that are considered to be utility. These include, but aren't limited to documents, screenshots, whiteboards etc. |
| `ARTS` | Media items containing art. |
| `CRAFTS` | Media items containing crafts. |
| `FASHION` | Media items related to fashion. |
| `HOUSES` | Media items containing houses. |
| `GARDENS` | Media items containing gardens. |
| `FLOWERS` | Media items containing flowers. |
| `HOLIDAYS` | Media items taken of holidays. |

## MediaTypeFilter

This filter defines the type of media items to be returned, for example, videos or photos. Only one media type is supported.

| JSON representation |
|---|
| ``` { "mediaTypes": [ enum (`https://developers.google.com/photos/library/reference/rest/v1/mediaItems/search#MediaType`) ] } ``` |

| Fields ||
|---|---|
| `mediaTypes[]` | ``enum (`https://developers.google.com/photos/library/reference/rest/v1/mediaItems/search#MediaType`)`` The types of media items to be included. This field should be populated with only one media type. If you specify multiple media types, it results in an error. |

## MediaType

The set of media types that can be searched for.

| Enums ||
|---|---|
| `ALL_MEDIA` | Treated as if no filters are applied. All media types are included. |
| `VIDEO` | All media items that are considered videos. This also includes movies the user has created using the Google Photos app. |
| `PHOTO` | All media items that are considered photos. This includes .bmp, .gif, .ico, .jpg (and other spellings), .tiff, .webp and special photo types such as iOS live photos, Android motion photos, panoramas, photospheres. |

## FeatureFilter

This filter defines the features that the media items should have.

| JSON representation |
|---|
| ``` { "includedFeatures": [ enum (`https://developers.google.com/photos/library/reference/rest/v1/mediaItems/search#Feature`) ] } ``` |

| Fields ||
|---|---|
| `includedFeatures[]` | ``enum (`https://developers.google.com/photos/library/reference/rest/v1/mediaItems/search#Feature`)`` The set of features to be included in the media item search results. The items in the set are ORed and may match any of the specified features. |

## Feature

The set of features that you can filter on.

| Enums ||
|---|---|
| `NONE` | Treated as if no filters are applied. All features are included. |
| `FAVORITES` | Media items that the user has marked as favorites in the Google Photos app. |