Method: mediaItems.search

Searches for media items in a user's Google Photos library. If no filters are set, then all media items in the user's library are returned. If an album is set, all media items in the specified album are returned. If filters are specified, 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 syntax.

Request body

The request body contains data with the following structure:

JSON representation 
{
  "albumId": string,
  "pageSize": integer,
  "pageToken": string,
  "filters": {
    object (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 (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 dateFilter is used. When this field is not specified, results are displayed newest first, oldest last by their creationTime. 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 includeArchivedMedia and excludeNonAppCreatedData. 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 (MediaItem)
    }
  ],
  "nextPageToken": string
}
Fields
mediaItems[]

object (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
  • https://www.googleapis.com/auth/photoslibrary.readonly
  • 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 (DateFilter)
  },
  "contentFilter": {
    object (ContentFilter)
  },
  "mediaTypeFilter": {
    object (MediaTypeFilter)
  },
  "featureFilter": {
    object (FeatureFilter)
  },
  "includeArchivedMedia": boolean,
  "excludeNonAppCreatedData": boolean
}
Fields
dateFilter

object (DateFilter)

Filters the media items based on their creation date.
contentFilter

object (ContentFilter)

Filters the media items based on their content.
mediaTypeFilter

object (MediaTypeFilter)

Filters the media items based on the type of media.
featureFilter

object (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 (Date)
    }
  ],
  "ranges": [
    {
      object (DateRange)
    }
  ]
}
Fields
dates[]

object (Date)

List of dates that match the media items' creation date. A maximum of 5 dates can be included per request.
ranges[]

object (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 Date.

JSON representation 
{
  "startDate": {
    object (Date)
  },
  "endDate": {
    object (Date)
  }
}
Fields
startDate

object (Date)

The start date (included as part of the range) in one of the formats described.
endDate

object (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 (ContentCategory)
  ],
  "excludedContentCategories": [
    enum (ContentCategory)
  ]
}
Fields
includedContentCategories[]

enum (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 (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 (MediaType)
  ]
}
Fields
mediaTypes[]

enum (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 (Feature)
  ]
}
Fields
includedFeatures[]

enum (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.