Search and apply filters

    Required authorization scopes

    The photoslibrary.readonly scope allows access to all media items in the user's library.

    Searching and applying filters to app-created content requires the photoslibrary.readonly.appcreateddata scope. For more information on scopes, see Authorization scopes .

    Available filters

    You can search a user's library of app-created media items for specific kinds of media. For example, you might only want items that are of animals, from a certain day, or you may want to exclude photos of receipts. You can exclude or include specific items by applying filters to an album or library listing. There are five available filters based on media item properties:

    Filters shouldn't be used in a mediaItems.search request if the albumId is set. If a filter is used when the albumId is set, an INVALID_ARGUMENT error (400) is returned.

    Results are sorted according to the media item creation time. The sort order can be modified for queries using date filters.

    Allow some time for newly uploaded media to appear in your searches. The media appears in unfiltered searches immediately.

    Media items that have a date in the future don't appear in filtered searches. They appear in unfiltered searches and album searches.

    Applying a filter

    To apply a filter, call mediaItems.search and specify the filter property.

    REST

    Here is a POST request:

     POST https://photoslibrary.googleapis.com/v1/mediaItems:search
Content-type: application/json
Authorization: Bearer oauth2-token 
 
{
  "pageSize": "100",
  "filters": { ... 
 } 
}

    The POST request returns the following response:

    {
  "mediaItems": [ ... 
 ], 
 "nextPageToken": " token-for-pagination 
" 
}

    Java

     try 
  
 { 
  
 // Create a new Filter object 
  
 Filters 
  
 filters 
  
 = 
  
 Filters 
 . 
 newBuilder 
 () 
  
 // .setContentFilter(...) 
  
 // .setDateFilter(...) 
  
 // ... 
  
 . 
 build 
 (); 
  
 // Specify the Filter object in the searchMediaItems call 
  
 SearchMediaItemsPagedResponse 
  
 response 
  
 = 
  
 photosLibraryClient 
 . 
 searchMediaItems 
 ( 
 filters 
 ); 
  
 for 
  
 ( 
 MediaItem 
  
 item 
  
 : 
  
 response 
 . 
 iterateAll 
 ()) 
  
 { 
  
 // ... 
  
 } 
 } 
  
 catch 
  
 ( 
 ApiException 
  
 e 
 ) 
  
 { 
  
 // Handle error 
 }

    PHP

     try { 
 $filtersBuilder = new FiltersBuilder(); 
 // $filtersBuilder->addIncludedCategory(...); 
 // $filtersBuilder->addDate(...); 
 // ... 
 // Make a search call with the options set in the filters builder 
 $response = $photosLibraryClient->searchMediaItems( 
 ['filters' => $filtersBuilder->build()] 
 ); 
 foreach ($response->iterateAllElements() as $element) { 
 // ... 
 } 
 } catch (\Google\ApiCore\ApiException $e) { 
 // Handle error 
 }

    For details, see List library contents, albums, and media items .

    Content categories

    All media items are processed and assigned labels. You can include and exclude any of the following categories.

    ANIMALS FASHION LANDMARKS RECEIPTS WEDDINGS
    ARTS
    		FLOWERS LANDSCAPES SCREENSHOTS WHITEBOARDS
    BIRTHDAYS
    		FOOD NIGHT SELFIES
    CITYSCAPES
    		GARDENS PEOPLE SPORT
    CRAFTS
    		HOLIDAYS PERFORMANCES TRAVEL
    DOCUMENTS
    		HOUSES PETS UTILITY

    Utility photos cover a broad range of media. This category generally includes items the user has captured to perform some task and is unlikely to want after that task is completed. It includes documents, receipts, screenshots, sticky notes, menus, and other similar media items.

    The categories are only as accurate as the equivalent labels in Google Photos. On occasion, items may be mislabeled, so we don't guarantee the accuracy of the content category filters.

    Including categories

    When you include multiple categories, media items that match any of the categories are included. A maximum of 10 categories can be included per request. This example filter returns any items of LANDSCAPES or LANDMARKS .

    REST

    {
  "filters": {
    "contentFilter": {
      "includedContentCategories": [
        "LANDSCAPES",
        "LANDMARKS"
      ]
    }
  }
}

    Java

     // Create a content filter that includes landmarks and landscapes 
 ContentFilter 
  
 contentFilter 
  
 = 
  
 ContentFilter 
 . 
 newBuilder 
 () 
  
 . 
 addIncludedContentCategories 
 ( 
 ContentCategory 
 . 
 LANDMARKS 
 ) 
  
 . 
 addIncludedContentCategories 
 ( 
 ContentCategory 
 . 
 LANDSCAPES 
 ) 
  
 . 
 build 
 (); 
 // Create a new Filters object 
 Filters 
  
 filters 
  
 = 
  
 Filters 
 . 
 newBuilder 
 () 
  
 . 
 setContentFilter 
 ( 
 contentFilter 
 ) 
  
 . 
 build 
 (); 
 // Specify the Filter object in the searchMediaItems call 
 SearchMediaItemsPagedResponse 
  
 response 
  
 = 
  
 photosLibraryClient 
 . 
 searchMediaItems 
 ( 
 filters 
 );

    PHP

     // Create a content filter that includes landmarks and landscapes 
 $filtersBuilder = new FiltersBuilder(); 
 $filtersBuilder->addIncludedCategory(ContentCategory::LANDMARKS); 
 $filtersBuilder->addIncludedCategory(ContentCategory::LANDSCAPES); 
 // Make a search call with the options set in the filters builder 
 $response = $photosLibraryClient->searchMediaItems( 
 ['filters' => $filtersBuilder->build()] 
 );

    Excluding categories

    Only media items that don't match any of the excluded categories are shown. Similar to the included categories, a maximum of 10 categories can be excluded per request.

    This filter returns any items that aren't PEOPLE or SELFIES :

    REST

    {
  "filters": {
    "contentFilter": {
      "excludedContentCategories": [
        "PEOPLE",
        "SELFIES"
      ]
    }
  }
}

    Java

     // Create a content filter that excludes people and selfies 
 ContentFilter 
  
 contentFilter 
  
 = 
  
 ContentFilter 
 . 
 newBuilder 
 () 
  
 . 
 addExcludedContentCategories 
 ( 
 ContentCategory 
 . 
 PEOPLE 
 ) 
  
 . 
 addExcludedContentCategories 
 ( 
 ContentCategory 
 . 
 SELFIES 
 ) 
  
 . 
 build 
 (); 
 // Create a new Filters object 
 Filters 
  
 filters 
  
 = 
  
 Filters 
 . 
 newBuilder 
 () 
  
 . 
 setContentFilter 
 ( 
 contentFilter 
 ) 
  
 . 
 build 
 (); 
 // Specify the Filter object in the searchMediaItems call 
 SearchMediaItemsPagedResponse 
  
 response 
  
 = 
  
 photosLibraryClient 
 . 
 searchMediaItems 
 ( 
 filters 
 );

    PHP

     // Create a content filter that excludes people and selfies 
 $filtersBuilder = new FiltersBuilder(); 
 $filtersBuilder->addExcludedCategory(ContentCategory::PEOPLE); 
 $filtersBuilder->addExcludedCategory(ContentCategory::SELFIES); 
 // Make a search call with the options set in the filters builder 
 $response = $photosLibraryClient->searchMediaItems( 
 ['filters' => $filtersBuilder->build()] 
 );

    Including and excluding multiple categories

    You can include some categories and exclude others. The following example returns LANDSCAPES and LANDMARKS , but removes any media items that contain PEOPLE or that are SELFIES :

    REST

    {
  "filters": {
    "contentFilter": {
      "includedContentCategories": [
        "LANDSCAPES",
        "LANDMARKS"
      ],
      "excludedContentCategories": [
        "PEOPLE",
        "SELFIES"
      ]
    }
  }
}

    Java

     // Create a content filter that excludes people and selfies and includes landmarks and landscapes 
 ContentFilter 
  
 contentFilter 
  
 = 
  
 ContentFilter 
 . 
 newBuilder 
 () 
  
 . 
 addIncludedContentCategories 
 ( 
 ContentCategory 
 . 
 LANDSCAPES 
 ) 
  
 . 
 addIncludedContentCategories 
 ( 
 ContentCategory 
 . 
 LANDMARKS 
 ) 
  
 . 
 addExcludedContentCategories 
 ( 
 ContentCategory 
 . 
 PEOPLE 
 ) 
  
 . 
 addExcludedContentCategories 
 ( 
 ContentCategory 
 . 
 SELFIES 
 ) 
  
 . 
 build 
 (); 
 // Create a new Filters object 
 Filters 
  
 filters 
  
 = 
  
 Filters 
 . 
 newBuilder 
 () 
  
 . 
 setContentFilter 
 ( 
 contentFilter 
 ) 
  
 . 
 build 
 (); 
 // Specify the Filters object in the searchMediaItems call 
 SearchMediaItemsPagedResponse 
  
 response 
  
 = 
  
 photosLibraryClient 
 . 
 searchMediaItems 
 ( 
 filters 
 );

    PHP

     // Create a content filter that excludes people and selfies and includes landmarks and landscapes 
 $filtersBuilder = new FiltersBuilder(); 
 $filtersBuilder->addIncludedCategory(ContentCategory::LANDMARKS); 
 $filtersBuilder->addIncludedCategory(ContentCategory::LANDSCAPES); 
 $filtersBuilder->addExcludedCategory(ContentCategory::PEOPLE); 
 $filtersBuilder->addExcludedCategory(ContentCategory::SELFIES); 
 // Make a search call with the options set in the filters builder 
 $response = $photosLibraryClient->searchMediaItems( 
 ['filters' => $filtersBuilder->build()] 
 );

    Dates and date ranges

    Date filters restrict the date of the returned results to a specified set of days. There are two ways to specify a date filter: dates, or ranges. Dates and ranges can be used together. Media items that match any of the dates or date ranges are returned. Optionally, the sort order of results can be modified.

    Dates

    A date contains a year, month, and day. The following formats are acceptable:

    • Year
    • Year, month
    • Year, month, day
    • Month, day
    • Month

    Where a component of the date is empty or set to zero, it's treated as a wildcard. For example, if you set the day and month, but not the year, you're requesting items from that day and month of any year:

    REST

    {
  "filters": {
    "dateFilter": {
      "dates": [
        {
          "month": 2,
          "day": 15
        }
      ]
    }
  }
}

    Java

     // Create a new com.google.type.Date object using a builder 
 // Note that there are different valid combinations as described above 
 Date 
  
 dayFebruary15 
  
 = 
  
 Date 
 . 
 newBuilder 
 () 
  
 . 
 setDay 
 ( 
 15 
 ) 
  
 . 
 setMonth 
 ( 
 2 
 ) 
  
 . 
 build 
 (); 
 // Create a new dateFilter. You can also set multiple dates here 
 DateFilter 
  
 dateFilter 
  
 = 
  
 DateFilter 
 . 
 newBuilder 
 () 
  
 . 
 addDates 
 ( 
 dayFebruary15 
 ) 
  
 . 
 build 
 (); 
 // Create a new Filters object 
 Filters 
  
 filters 
  
 = 
  
 Filters 
 . 
 newBuilder 
 () 
  
 . 
 setDateFilter 
 ( 
 dateFilter 
 ) 
  
 . 
 build 
 (); 
 // Specify the Filters object in the searchMediaItems call 
 SearchMediaItemsPagedResponse 
  
 response 
  
 = 
  
 photosLibraryClient 
 . 
 searchMediaItems 
 ( 
 filters 
 );

    PHP

     // Create a new Google\Type\Date object with a day and a month 
 // Note that there are different valid combinations as described above 
 $dateFebruary15 = new Date(); 
 $dateFebruary15->setDay(15); 
 $dateFebruary15->setMonth(2); 
 $filtersBuilder = new FiltersBuilder(); 
 // Add the date to the filter. You can also set multiple dates here 
 $filtersBuilder->addDate($dateFebruary15); 
 // Make a search call with the options set in the filters builder 
 $response = $photosLibraryClient->searchMediaItems( 
 ['filters' => $filtersBuilder->build()] 
 );

    Date ranges

    Date ranges provide more flexibility than dates. For example, rather than adding multiple dates, a date range can be used to see a set of days within a month.

    A date range has a startDate and endDate , both of which must be set. Each date in the range has the same format constraints as described in Dates . The dates must have the same format: if the start date is a year and a month, the end date must also be a year and a month. The ranges are applied inclusively, the start and end dates are included in the applied filter:

    REST

    {
  "filters": {
    "dateFilter": {
      "ranges": [
        {
          "startDate": {
            "year": 2014,
            "month": 6,
            "day": 12
          },
          "endDate": {
            "year": 2014,
            "month": 7,
            "day": 13
          }
        }
      ]
    }
  }
}

    Java

     // Create new com.google.type.Date objects for two dates 
 Date 
  
 day2014June12 
  
 = 
  
 Date 
 . 
 newBuilder 
 () 
  
 . 
 setDay 
 ( 
 12 
 ) 
  
 . 
 setMonth 
 ( 
 6 
 ) 
  
 . 
 setYear 
 ( 
 2014 
 ) 
  
 . 
 build 
 (); 
 Date 
  
 day2014July13 
  
 = 
  
 Date 
 . 
 newBuilder 
 () 
  
 . 
 setDay 
 ( 
 13 
 ) 
  
 . 
 setMonth 
 ( 
 7 
 ) 
  
 . 
 setYear 
 ( 
 2014 
 ) 
  
 . 
 build 
 (); 
 // Create a DateRange from these two dates 
 DateRange 
  
 dateRange 
  
 = 
  
 DateRange 
 . 
 newBuilder 
 () 
  
 . 
 setStartDate 
 ( 
 day2014June12 
 ) 
  
 . 
 setEndDate 
 ( 
 day2014July13 
 ) 
  
 . 
 build 
 (); 
 // Create a new dateFilter with the date range. You can also set multiple date ranges here 
 DateFilter 
  
 dateFilter 
  
 = 
  
 DateFilter 
 . 
 newBuilder 
 () 
  
 . 
 addRanges 
 ( 
 dateRange 
 ) 
  
 . 
 build 
 (); 
 // Create a new Filters object 
 Filters 
  
 filters 
  
 = 
  
 Filters 
 . 
 newBuilder 
 () 
  
 . 
 setDateFilter 
 ( 
 dateFilter 
 ) 
  
 . 
 build 
 (); 
 // Specify the Filters object in the searchMediaItems call 
 SearchMediaItemsPagedResponse 
  
 response 
  
 = 
  
 photosLibraryClient 
 . 
 searchMediaItems 
 ( 
 filters 
 );

    PHP

     // Create two new Google\Type\Date objects 
 $date2014June12 = new Date(); 
 $date2014June12->setDay(12); 
 $date2014June12->setMonth(6); 
 $date2014June12->setYear(2014); 
 $date2014July13 = new Date(); 
 $date2014July13->setDay(13); 
 $date2014July13->setMonth(7); 
 $date2014July13->setYear(2014); 
 // Add the two dates as a date range to the filter 
 // You can also set multiple date ranges here 
 $filtersBuilder = new FiltersBuilder(); 
 $filtersBuilder->addDateRange($date2014June12, $date2014July13); 
 // Make a search call with the options set in the filters builder 
 $response = $photosLibraryClient->searchMediaItems( 
 ['filters' => $filtersBuilder->build()] 
 );

    Combining dates and date ranges

    You can use multiple dates and multiple date ranges at the same time. Items that fall within any of these dates are included in the results. Separate dates and date ranges don't need to follow the same format, but the start and end dates of individual ranges do:

    REST

    {
  "filters": {
    "dateFilter": {
      "dates": [
        {
          "year": 2013
        },
        {
          "year": 2011,
          "month": 11
        }
      ],
      "ranges": [
        {
          "startDate": {
            "month": 1
          },
          "endDate": {
            "month": 3
          }
        },
        {
          "startDate": {
            "month": 3,
            "day": 24
          },
          "endDate": {
            "month": 5,
            "day": 2
          }
        }
      ]
    }
  }
}

    Java

     // Create a new com.google.type.Date object for the year 2013 
 Date 
  
 day2013 
  
 = 
  
 Date 
 . 
 newBuilder 
 () 
  
 . 
 setYear 
 ( 
 2013 
 ) 
  
 . 
 build 
 (); 
 // Create a new com.google.type.Date object for November 2011 
 Date 
  
 day2011November 
  
 = 
  
 Date 
 . 
 newBuilder 
 () 
  
 . 
 setMonth 
 ( 
 11 
 ) 
  
 . 
 setYear 
 ( 
 2011 
 ) 
  
 . 
 build 
 (); 
 // Create a date range for January to March 
 DateRange 
  
 dateRangeJanuaryToMarch 
  
 = 
  
 DateRange 
 . 
 newBuilder 
 () 
  
 . 
 setStartDate 
 ( 
 Date 
 . 
 newBuilder 
 (). 
 setMonth 
 ( 
 1 
 ). 
 build 
 ()) 
  
 . 
 setEndDate 
 ( 
 Date 
 . 
 newBuilder 
 (). 
 setMonth 
 ( 
 3 
 ). 
 build 
 ()) 
  
 . 
 build 
 (); 
 // Create a date range for March 24 to May 2 
 DateRange 
  
 dateRangeMarch24toMay2 
  
 = 
  
 DateRange 
 . 
 newBuilder 
 () 
  
 . 
 setStartDate 
 ( 
 Date 
 . 
 newBuilder 
 (). 
 setMonth 
 ( 
 3 
 ). 
 setDay 
 ( 
 24 
 ). 
 build 
 ()) 
  
 . 
 setEndDate 
 ( 
 Date 
 . 
 newBuilder 
 (). 
 setMonth 
 ( 
 5 
 ). 
 setDay 
 ( 
 2 
 ). 
 build 
 ()) 
  
 . 
 build 
 (); 
 // Create a new dateFilter with the dates and date ranges 
 DateFilter 
  
 dateFilter 
  
 = 
  
 DateFilter 
 . 
 newBuilder 
 () 
  
 . 
 addDates 
 ( 
 day2013 
 ) 
  
 . 
 addDates 
 ( 
 day2011November 
 ) 
  
 . 
 addRanges 
 ( 
 dateRangeJanuaryToMarch 
 ) 
  
 . 
 addRanges 
 ( 
 dateRangeMarch24toMay2 
 ) 
  
 . 
 build 
 (); 
 // Create a new Filters object 
 Filters 
  
 filters 
  
 = 
  
 Filters 
 . 
 newBuilder 
 () 
  
 . 
 setDateFilter 
 ( 
 dateFilter 
 ) 
  
 . 
 build 
 (); 
 // Specify the Filter object in the searchMediaItems call 
 SearchMediaItemsPagedResponse 
  
 response 
  
 = 
  
 photosLibraryClient 
 . 
 searchMediaItems 
 ( 
 filters 
 );

    PHP

     // Create a new Google\Type\Date object for the year 2013 
 $date2013 = new Date(); 
 $date2013->setYear(2013); 
 // Create a new Google\Type\Date object for November 2011 
 $dateNovember2011 = new Date(); 
 $dateNovember2011->setMonth(11); 
 $dateNovember2011->setYear(2011); 
 $filtersBuilder = new FiltersBuilder(); 
 // Create a date range for January to March 
 $filtersBuilder->addDateRange((new Date())->setMonth(1), 
 (new Date())->setMonth(3)); 
 // Create a date range for March 24 to May 2 
 $filtersBuilder->addDateRange((new Date())->setMonth(3)->setDay(24), 
 (new Date())->setMonth(5)->setDay(2)); 
 $filtersBuilder->addDate($date2013); 
 $filtersBuilder->addDate($dateNovember2011); 
 // Make a search call with the options set in the filters builder 
 $response = $photosLibraryClient->searchMediaItems( 
 ['filters' => $filtersBuilder->build()] 
 );

    Media item features

    Feature filters restrict results to items that have specific features, for example that have been marked as favorites in the Google Photos application.

    Favorites

    Include the FAVORITES item feature in the FeatureFilter to only return media items that have been marked as favorites by the user:

    REST

    {
  "filters" : {
    "featureFilter": {
      "includedFeatures": [
        "FAVORITES"
      ]
    }
  }
}

    Java

     // Create a new FeatureFilter for favorite media items 
 FeatureFilter 
  
 featureFilter 
  
 = 
  
 FeatureFilter 
 . 
 newBuilder 
 () 
  
 . 
 addIncludedFeatures 
 ( 
 Feature 
 . 
 FAVORITES 
 ) 
  
 . 
 build 
 (); 
 // Create a new Filters object 
 Filters 
  
 filters 
  
 = 
  
 Filters 
 . 
 newBuilder 
 () 
  
 . 
 setFeatureFilter 
 ( 
 featureFilter 
 ) 
  
 . 
 build 
 (); 
 // Specify the Filters object in the searchMediaItems call 
 SearchMediaItemsPagedResponse 
  
 response 
  
 = 
  
 photosLibraryClient 
 . 
 searchMediaItems 
 ( 
 filters 
 );

    PHP

     // Create a new FeatureFilter for favorite media items 
 $filtersBuilder = new FiltersBuilder(); 
 $filtersBuilder->addIncludedFeature(Feature::FAVORITES); 
 // Make a search call with the options set in the filters builder 
 $response = $photosLibraryClient->searchMediaItems( 
 ['filters' => $filtersBuilder->build()] 
 );

    Media types

    You can limit results to the type of media: either photo or video .

    Photo

    A PHOTO can be any of several image formats:

    BMP JPG
    GIF PNG
    HEIC TIFF
    ICO WEBP

    It also includes special photo types like iOS live photos, motion photos, panoramas, photo spheres, and VR photos.

    Video

    A VIDEO can be various video formats:

    3GP MMV
    3G2 MOD
    ASF MOV
    AVI MP4
    DIVX MPG
    M2T MTS
    M2TS TOD
    M4V WMV
    MKV

    VIDEO also includes special video formats like the following: VR videos, slow-motion videos, and animations created in the Google Photos application.

    The following example filters by PHOTO :

    REST

    {
  "filters": {
    "mediaTypeFilter": {
      "mediaTypes": [
        "PHOTO"
      ]
    }
  }
}

    Java

     // Create a new MediaTypeFilter for Photo media items 
 MediaTypeFilter 
  
 mediaType 
  
 = 
  
 MediaTypeFilter 
 . 
 newBuilder 
 () 
  
 . 
 addMediaTypes 
 ( 
 MediaType 
 . 
 PHOTO 
 ) 
  
 . 
 build 
 (); 
 // Create a new Filters object 
 Filters 
  
 filters 
  
 = 
  
 Filters 
 . 
 newBuilder 
 () 
  
 . 
 setMediaTypeFilter 
 ( 
 mediaType 
 ) 
  
 . 
 build 
 (); 
 // Specify the Filters object in the searchMediaItems call 
 SearchMediaItemsPagedResponse 
  
 response 
  
 = 
  
 photosLibraryClient 
 . 
 searchMediaItems 
 ( 
 filters 
 );

    PHP

     // Create a new MediaTypeFilter for Photo media items 
 $filtersBuilder = new FiltersBuilder(); 
 $filtersBuilder->setMediaType(MediaType::PHOTO); 
 // Make a search call with the options set in the filters builder 
 $response = $photosLibraryClient->searchMediaItems( 
 ['filters' => $filtersBuilder->build()] 
 );

    Multiple media types filters can't be combined.

    Archived state

    Your users may have archived some of their photos. By default, archived photos aren't returned in searches. To include archived items, you can set a flag in the filter as shown in the following example:

    REST

    {
  "filters": {
    "includeArchivedMedia": true
  }
}

    Java

     // Create a new Filters object that includes archived media 
 Filters 
  
 filters 
  
 = 
  
 Filters 
 . 
 newBuilder 
 () 
  
 . 
 setIncludeArchivedMedia 
 ( 
 true 
 ) 
  
 . 
 build 
 (); 
 // Specify the Filters object in the searchMediaItems call 
 SearchMediaItemsPagedResponse 
  
 response 
  
 = 
  
 photosLibraryClient 
 . 
 searchMediaItems 
 ( 
 filters 
 );

    PHP

     // Create a new Filters object that includes archived media 
 $filtersBuilder = new FiltersBuilder(); 
 $filtersBuilder->setIncludeArchivedMedia(true); 
 // Make a search call with the options set in the filters builder 
 $response = $photosLibraryClient->searchMediaItems( 
 ['filters' => $filtersBuilder->build()] 
 );

    Combining filters

    Different kinds of filters can be combined. Only items that match all of the requested features are returned.

    When combining filters, the formatting restrictions for each filter type are the same as when they're used individually. In the following example, only photos that have been categorized as SPORT and that are from either 2014 or 2010 are returned:

    REST

    {
  "filters": {
    "contentFilter": {
      "includedContentCategories": [
        "SPORT"
      ]
    },
    "dateFilter": {
      "dates": [
        {
          "year": 2014
        },
        {
          "year": 2010
        }
      ]
    },
    "mediaTypeFilter": {
      "mediaTypes": [
        "PHOTO"
      ]
    }
  }
}

    Java

     // Create a new ContentFilter that only includes SPORT items 
 ContentFilter 
  
 contentFilter 
  
 = 
  
 ContentFilter 
 . 
 newBuilder 
 () 
  
 . 
 addIncludedContentCategories 
 ( 
 ContentCategory 
 . 
 SPORT 
 ) 
  
 . 
 build 
 (); 
 // Create a new media type filter that only includes PHOTO media items 
 MediaTypeFilter 
  
 mediaTypeFilter 
  
 = 
  
 MediaTypeFilter 
 . 
 newBuilder 
 () 
  
 . 
 addMediaTypes 
 ( 
 MediaType 
 . 
 PHOTO 
 ) 
  
 . 
 build 
 (); 
 // Create a new DateFilter that only includes items from 2010 or 2014 
 Date 
  
 year2014 
  
 = 
  
 Date 
 . 
 newBuilder 
 (). 
 setYear 
 ( 
 2014 
 ). 
 build 
 (); 
 Date 
  
 year2010 
  
 = 
  
 Date 
 . 
 newBuilder 
 (). 
 setYear 
 ( 
 2010 
 ). 
 build 
 (); 
 DateFilter 
  
 dateFilter 
  
 = 
  
 DateFilter 
 . 
 newBuilder 
 () 
  
 . 
 addDates 
 ( 
 year2010 
 ) 
  
 . 
 addDates 
 ( 
 year2014 
 ) 
  
 . 
 build 
 (); 
 // Create a new Filters object combining these filters 
 Filters 
  
 filters 
  
 = 
  
 Filters 
 . 
 newBuilder 
 () 
  
 . 
 setDateFilter 
 ( 
 dateFilter 
 ) 
  
 . 
 setMediaTypeFilter 
 ( 
 mediaTypeFilter 
 ) 
  
 . 
 setContentFilter 
 ( 
 contentFilter 
 ) 
  
 . 
 build 
 (); 
 // Specify the Filter object in the searchMediaItems call 
 SearchMediaItemsPagedResponse 
  
 response 
  
 = 
  
 photosLibraryClient 
 . 
 searchMediaItems 
 ( 
 filters 
 );

    PHP

     // Create a new ContentFilter 
 $filtersBuilder = new FiltersBuilder(); 
 // Only include SPORT items 
 $filtersBuilder->addIncludedCategory(ContentCategory::SPORT); 
 // Only include PHOTO media items 
 $filtersBuilder->setMediaType(MediaType::PHOTO); 
 // Only include items from 2010 or 2014 
 $year2014 = new Date(); 
 $year2014->setYear(2014); 
 $year2010 = new Date(); 
 $year2010->setYear(2010); 
 $filtersBuilder->addDateRange($year2010, $year2014); 
 // Make a search call with the options set in the filters builder 
 // Filters have been combined in the filter builder 
 $response = $photosLibraryClient->searchMediaItems( 
 ['filters' => $filtersBuilder->build()] 
 );

    Sorting results

    Only queries using date filters can be sorted.

    If you do not specify a sorting option, then your results will be sorted in descending order (newest first).

    This table shows the supported options for the orderBy parameter:

    orderBy parameter
    MediaMetadata.creation_time desc
    Returns media items in descending order (newest items first)
    MediaMetadata.creation_time
    Returns media items in ascending order (oldest items first)

    The following example returns all media items from 2017, showing the oldest first and the newest last.

    REST

    {
  "filters": {
    "dateFilter": {
      "dates": [
        {
          "year": 2017
        }
      ]
    }
  },
  "orderBy": "MediaMetadata.creation_time"
}

    Java

     // Create a new dateFilter for the year 2017. 
 DateFilter 
  
 dateFilter 
  
 = 
  
 DateFilter 
 . 
 newBuilder 
 () 
  
 . 
 addDates 
 ( 
 Date 
 . 
 newBuilder 
 (). 
 setYear 
 ( 
 2017 
 )) 
  
 . 
 build 
 (); 
 // Create a new Filters object 
 Filters 
  
 filters 
  
 = 
  
 Filters 
 . 
 newBuilder 
 () 
  
 . 
 setDateFilter 
 ( 
 dateFilter 
 ) 
  
 . 
 build 
 (); 
 // Sort results by oldest item first. 
 final 
  
 OrderBy 
  
 newestFirstOrder 
  
 = 
  
 OrderBy 
 . 
 MEDIAMETADATA_CREATION_TIME 
 ; 
 // Specify the filter and sort order in the searchMediaItems call. 
 SearchMediaItemsPagedResponse 
  
 response 
  
 = 
  
 photosLibraryClient 
 . 
 searchMediaItems 
 ( 
 filters 
 , 
  
 newestFirstOrder 
 );

    PHP

     // Create a new dateFilter for the year 2017. 
 $filtersBuilder = new FiltersBuilder(); 
 $filtersBuilder->addDate((new Date())->setYear(2017)); 
 // Make a search call with the options set in the filters builder and sort 
 // the results by oldest item first. 
 $response = $photosLibraryClient->searchMediaItems( 
 [ 
 'filters' => $filtersBuilder->build(), 
 'orderBy' => OrderBy::MEDIAMETADATA_CREATION_TIME 
 ] 
 );
    Create a Mobile Website
    View Site in Mobile | Classic
    Share by: