Pesquisar e aplicar filtros

Escopos de autorização obrigatórios

A API Google Photos Library tem vários escopos usados para acessar itens de mídia e álbuns. Os itens de mídia retornados de várias chamadas são diferentes com base nos escopos solicitados pelo desenvolvedor.

O escopo photoslibrary.readonly permite acesso a todos os itens de mídia na biblioteca do usuário. O escopo photoslibrary.readonly.appcreateddata permite acesso apenas a itens de mídia criados pelo app. Para mais informações, consulte Escopos de autorização.

Filtros disponíveis

Você pode pesquisar tipos específicos de mídia na biblioteca de um usuário. Por exemplo, você pode querer apenas itens de animais, de um determinado dia ou excluir fotos de comprovantes. Você pode excluir ou incluir itens específicos aplicando filtros a um álbum ou uma listagem de biblioteca. Há cinco filtros disponíveis com base nas propriedades do item de mídia:

• Categorias de conteúdo (includedContentCategories, excludedContentCategories)
• Datas e períodos (dates, ranges)
• Recursos (featureFilter)
• Tipos de mídia (mediaTypeFilter)
• Estado arquivado (includeArchivedMedia)

Os filtros não podem ser usados em uma solicitação mediaItems:search se albumId estiver definido. Se um filtro for usado quando o albumId for definido, um erro INVALID_ARGUMENT (400) será retornado.

Os resultados são classificados de acordo com o horário de criação do item de mídia. A ordem de classificação pode ser modificada para consultas que usam filtros de data.

Aguarde algum tempo para que a mídia recém-enviada apareça nas suas pesquisas. A mídia aparece imediatamente em pesquisas não filtradas.

Os itens de mídia que têm uma data no futuro não aparecem nas pesquisas filtradas. Elas aparecem em pesquisas sem filtros e em álbuns.

Aplicando um filtro

Para aplicar um filtro, chame mediaItems.search e especifique a propriedade filter.

REST

Esta é uma solicitação POST:

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

A solicitação POST retorna a seguinte resposta:

{
  "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
}

Para saber mais, consulte Listar conteúdos, álbuns e itens de mídia da biblioteca.

Categorias de conteúdo

Todos os itens de mídia são processados e recebem rótulos. É possível incluir e excluir qualquer uma das categorias a seguir.

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

As fotos dos utilitários abrangem várias mídias. Essa categoria geralmente inclui itens que o usuário capturou para realizar alguma tarefa e que provavelmente não vai querer depois que ela for concluída. Isso inclui documentos, recibos, capturas de tela, notas adesivas, menus e outros itens de mídia semelhantes.

Elas são tão precisas quanto os rótulos equivalentes no Google Fotos. Às vezes, os itens podem ser rotulados incorretamente, por isso não garantimos a precisão dos filtros de categoria de conteúdo.

Incluir categorias

Ao incluir várias categorias, os itens de mídia que correspondem a qualquer uma das categorias serão incluídos. É possível incluir até 10 categorias por solicitação. Este filtro de exemplo retorna todos os itens de LANDSCAPES ou 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()]
);

Exclusão de categorias

Somente os itens de mídia que não correspondem a nenhuma das categorias excluídas são mostrados. De maneira semelhante às categorias incluídas, é possível excluir até 10 categorias por solicitação.

Esse filtro retorna os itens que não são PEOPLE nem 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()]
);

Incluir e excluir várias categorias

É possível incluir algumas categorias e excluir outras. O exemplo a seguir retorna LANDSCAPES e LANDMARKS, mas remove todos os itens de mídia que contenham PEOPLE ou que sejam 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()]
);

Datas e períodos

Os filtros de data restringem a data dos resultados retornados a um conjunto especificado de dias. Há duas maneiras de especificar um filtro de data: datas ou períodos. Datas e intervalos podem ser usados juntos. Os itens de mídia que correspondem a qualquer uma das datas ou intervalos de datas são retornados. É possível modificar a ordem de classificação dos resultados.

Observação: itens de mídia enviados sem metadados que especificam a data em que o item de mídia foi capturado não serão retornados em consultas que usam filtros de data. Nesse caso, o tempo de upload do servidor do Google Fotos não é usado como substituto.

Datas

Uma data contém um ano, um mês e um dia. Os seguintes formatos são aceitos:

• Ano
• Ano, mês
• Ano, mês, dia
• Mês, dia
• Mês

Quando um componente da data está vazio ou é definido como zero, ele é tratado como um caractere curinga. Por exemplo, se definir o dia e o mês, mas não o ano, você solicitará itens desse dia e mês de qualquer ano:

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()]
);

Períodos

Os períodos oferecem mais flexibilidade do que as datas. Por exemplo, em vez de adicionar várias datas, use um período para ver um conjunto de dias de um mês.

Um período tem startDate e endDate, que precisam ser definidos. Cada data no intervalo tem as mesmas restrições de formato descritas em Datas. As datas precisam ter o mesmo formato: se a data de início for um ano e um mês, a data de término também precisará ser um ano e um mês. Os períodos são aplicados de forma inclusiva, e as datas de início e término são incluídas no filtro aplicado:

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()]
    );

Combinar datas e períodos

Você pode usar várias datas e períodos ao mesmo tempo. Os itens que se enquadram em qualquer uma dessas datas são incluídos nos resultados. Datas e períodos diferentes não precisam seguir o mesmo formato, mas as datas de início e término de períodos individuais precisam:

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()]
);

Recursos de item de mídia

Os filtros de recursos restringem os resultados a itens com recursos específicos, por exemplo, marcados como favoritos no aplicativo Google Fotos.

Favoritos

Inclua o recurso do item FAVORITES no FeatureFilter para retornar apenas itens de mídia que foram marcados como favoritos pelo usuário:

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()]
);

Tipos de mídia

Você pode limitar os resultados ao tipo de mídia: foto ou vídeo.

Foto

Um PHOTO pode ser qualquer um dos vários formatos de imagem:

BMP	JPG
GIF	PNG
HEIC	TIFF
ICO	WEBP

Ele também inclui tipos de fotos especiais, como fotos ao vivo do iOS, fotos com movimento, panoramas, Photo Spheres e fotos com RV.

Video

Um VIDEO pode estar em vários formatos de vídeo:

3GP	MMV
Conexão 3G2	MOD
ASF	MOV
AVI	MP4
DIVX	MPG
M2T	MTS
M2TS	TOD
M4 v	WMV
MKV

O VIDEO também inclui formatos de vídeo especiais, como os seguintes: vídeos de RV, em câmera lenta e animações criadas no app Google Fotos.

O exemplo a seguir filtra por 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()]
);

Não é possível combinar vários filtros de tipos de mídia.

Excluir dados que não foram criados pelo app

Para excluir os itens de mídia que não foram criados pelo app, defina o filtro excludeNonAppCreatedData, conforme mostrado no exemplo abaixo:

REST

{
  "filters": {
    "excludeNonAppCreatedData": true
  }
}

Java

// Create a new Filters object that excludes media not created by your app
Filters filters = Filters.newBuilder()
    .setExcludeNonAppCreatedData(true)
    .build();

// Specify the Filters object in the searchMediaItems call
SearchMediaItemsPagedResponse response = photosLibraryClient.searchMediaItems(filters);

PHP

// Create a new Filters object that excludes media not created by your app
$filtersBuilder = new FiltersBuilder();
$filtersBuilder->setExcludeNonAppCreatedData(true);

// Make a search call with the options set in the filters builder
$response = $photosLibraryClient->searchMediaItems(
    ['filters' => $filtersBuilder->build()]
);

Se você estiver usando o escopo .readonly.appcreateddata, esse filtro será ignorado.

Estado arquivado

Talvez seus usuários tenham arquivado algumas fotos. Por padrão, as fotos arquivadas não são retornadas nas pesquisas. Para incluir itens arquivados, defina uma flag no filtro, conforme mostrado no exemplo a seguir:

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()]
);

Combinação de filtros

Diferentes tipos de filtros podem ser combinados. Somente os itens que correspondem a todos os recursos solicitados são retornados.

Ao combinar filtros, as restrições de formatação para cada tipo de filtro são as mesmas de quando eles são usados individualmente. No exemplo a seguir, apenas as fotos que foram categorizadas como SPORT e que são de 2014 ou 2010 são retornadas:

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()]
);

Classificar os resultados

Somente consultas que usam filtros de data podem ser classificadas.

Se você não especificar uma opção de classificação, os resultados serão classificados em ordem decrescente (mais recentes primeiro).

Esta tabela mostra as opções compatíveis para o parâmetro orderBy:

Parâmetro orderBy
MediaMetadata.creation_time desc	Retorna os itens de mídia em ordem decrescente (os itens mais recentes primeiro)
MediaMetadata.creation_time	Retorna itens de mídia em ordem crescente (os mais antigos primeiro)

O exemplo a seguir retorna todos os itens de mídia de 2017, mostrando o mais antigo primeiro e o mais recente por último.

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
    ]
);