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": number,
  "pageToken": string,
  "filters": {
    object (Filters)
  }
}
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

number

Maximum number of media items to return in the response. The default number of media items to return at a time is 25. The maximum pageSize 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.

Response body

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

List of media items that match the search parameters.

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.

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. The day may be 0 to represent a year and month where the day isn't significant, such as a whole calendar month. The month may be 0 to represent a a day and a year where the month isn't signficant, like when you want to specify the same day in every month of a year or a specific year. The year may be 0 to represent a month and day independent of year, like an anniversary date.

JSON representation
{
  "year": number,
  "month": number,
  "day": number
}
Fields
year

number

Year of date. Must be from 1 to 9999, or 0 if specifying a date without a year.

month

number

Month of year. Must be from 1 to 12, or 0 if specifying a year without a month and day.

day

number

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. All the specified media types are treated as an OR when used together.

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.

Try it!