必要な認可スコープ
Google Photos Library API には、メディア アイテムとアルバムへのアクセスに使用される複数のスコープが含まれています。さまざまな呼び出しから返されるメディア アイテムは、デベロッパーがリクエストしたスコープによって異なります。
photoslibrary.readonly
スコープを使用すると、ユーザーのライブラリ内のすべてのメディア アイテムにアクセスできます。photoslibrary.readonly.appcreateddata
スコープを使用すると、アプリによって作成されたメディア アイテムにのみアクセスできます。詳しくは、承認スコープをご覧ください。
使用できるフィルタ
ユーザーのライブラリで特定の種類のメディアを検索できます。たとえば、特定の日の動物のアイテムのみが必要な場合や、領収書の写真を除外したい場合などです。特定のアイテムを除外または含めるには、アルバムまたはライブラリのリストにフィルタを適用します。メディア アイテムのプロパティに基づいて、次の 5 つのフィルタを使用できます。
- コンテンツ カテゴリ(
includedContentCategories
、excludedContentCategories
) - 日付と期間(
dates
、ranges
) - 機能(
featureFilter
) - メディアタイプ(
mediaTypeFilter
) - アーカイブされた状態(
includeArchivedMedia
)
albumId
が設定されている場合、mediaItems:search
リクエストでフィルタを使用しないでください。artistId が設定されているときにフィルタを使用すると、INVALID_ARGUMENT
エラー(400)が返されます。
結果はメディア アイテムの作成時間順に表示されます。日付フィルタを使用するクエリでは、並べ替え順を変更できます。
新しくアップロードしたメディアが検索結果に表示されるまで、しばらくお待ちください。フィルタされていない検索結果に、メディアがすぐに表示されます。
将来の日付を持つメディア アイテムは、フィルタ検索に表示されません。フィルタされていない検索結果やアルバム検索結果に表示されます。
フィルタを適用する
フィルタを適用するには、mediaItems.search
を呼び出して filter
プロパティを指定します。
REST
POST リクエストは次のようになります。
POST https://photoslibrary.googleapis.com/v1/mediaItems:search
Content-type: application/json
Authorization: Bearer oauth2-token
{
"pageSize": "100",
"filters": {
...
}
}
POST リクエストは次のレスポンスを返します。
{ "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 }
詳しくは、ライブラリのコンテンツ、アルバム、メディア アイテムを一覧表示するをご覧ください。
コンテンツ カテゴリ
すべてのメディア アイテムが処理されて、ラベルが割り当てられます。次のカテゴリを含めたり除外したりできます。
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 |
実用系の写真は、幅広い種類のメディアを対象としています。このカテゴリには通常、ユーザーがなんらかのタスクを実行するためにキャプチャしたアイテムが含まれ、そのタスクの完了後に必要とされる可能性は低くなります。ドキュメント、領収書、スクリーンショット、付箋、メニューなどのメディア アイテムが含まれます。
カテゴリの精度は、Google フォトの同等のラベルと同等です。アイテムに誤ったラベルが付けられることがあるため、コンテンツ カテゴリ フィルタの正確性は保証されません。
カテゴリを含める
複数のカテゴリを指定すると、いずれかのカテゴリに一致するメディア アイテムが含まれます。リクエストごとに最大 10 個のカテゴリを含めることができます。この例のフィルタは、LANDSCAPES
または 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()] );
カテゴリの除外
除外されたカテゴリのいずれにも一致しないメディア アイテムのみが表示されます。 含めるカテゴリと同様に、1 回のリクエストで最大 10 個のカテゴリを除外できます。
このフィルタは、PEOPLE
でも 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()] );
複数のカテゴリの追加と除外
カテゴリを追加し、他のカテゴリを除外することができます。次の例では、LANDSCAPES
と LANDMARKS
が返されますが、PEOPLE
を含むメディア アイテムまたは 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()] );
日付と期間
日付フィルタは、返される結果の日付を特定の日付に制限します。日付フィルタを指定するには、日付と期間の 2 つの方法があります。日付と範囲は一緒に使用できます。日付または日付範囲のいずれかに一致するメディア アイテムが返されます。必要に応じて、結果の並べ替え順を変更できます。
期間
日付には年、月、日が含まれます。使用できる形式は次のとおりです。
- 年
- 年、月
- 年、月、日
- 月、日
- 月
日付の要素が空かゼロに設定されている場合は、ワイルドカードとして扱われます。たとえば、年ではなく日と月を設定した場合は、任意の年のその日と月のアイテムがリクエストされます。
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()] );
期間
期間の方が日付よりも柔軟に指定することができます。たとえば、複数の日付を追加する代わりに、期間を使用して 1 か月内の複数の日を表示できます。
期間には startDate
と endDate
があり、どちらも設定する必要があります。期間内の各日付には、日付で説明されている形式と同じ制約が適用されます。日付は同じ形式にする必要があります。開始日が年と月の場合、終了日も年と月にする必要があります。期間はすべて適用され、開始日と終了日は適用されたフィルタに含まれます。
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()] );
日付と期間の組み合わせ
複数の日付と複数の期間を同時に使用できます。これらの日付のいずれかに該当するアイテムが結果に含まれます。別々の日付と期間が同じ形式である必要はありませんが、個々の範囲の開始日と終了日は同じ形式に従う必要があります。
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()] );
メディア アイテムの機能
機能フィルタでは、検索結果を、特定の機能を備えたアイテム(Google フォト アプリケーションでお気に入りとしてマークされているものなど)に限定します。
お気に入り
FeatureFilter
に FAVORITES
アイテム機能を追加して、ユーザーがお気に入りとしてマークしたメディア アイテムのみを返します。
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()] );
メディアの種類
写真
PHOTO
は、次のいずれかの画像形式になります。
BMP | JPG |
GIF | PNG |
HEIC | TIFF |
ICO | WebP |
また、iOS の Live Photos、モーション フォト、パノラマ、360°写真、VR フォトなどの特殊な写真も含まれます。
動画
VIDEO
には、次のようなさまざまな動画形式があります。
3GP | MMV |
3G2 | MOD |
ASF | MOV |
AVI | MP4 |
DIVX | MPG |
M2T | MTS |
M2TS | TOD |
M4V | WMV |
MKV |
VIDEO
には、Google フォト アプリで作成された VR 動画、スローモーション動画、アニメーションなどの特殊な動画形式も含まれます。
次の例では、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()] );
複数のメディアタイプのフィルタを組み合わせることはできません。
アプリ以外で作成されたデータを除外する
アプリ以外で作成されたメディア アイテムを除外するには、次の例に示すように excludeNonAppCreatedData
フィルタを設定します。
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()] );
.readonly.appcreateddata
スコープを使用している場合、このフィルタは無視されます。
アーカイブ状態
ユーザーが一部の写真をアーカイブした可能性があります。デフォルトでは、アーカイブされた写真は検索で返されません。アーカイブされたアイテムを含めるには、次の例に示すようにフィルタにフラグを設定します。
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()] );
フィルタの組み合わせ
さまざまな種類のフィルタを組み合わせることができます。リクエストされた機能すべてに一致するアイテムのみが返されます。
フィルタを組み合わせる場合、各フィルタタイプのフォーマット制限は、個別に使用する場合と同じです。次の例では、SPORT
に分類され、2014 年または 2010 年のいずれかの写真のみが返されます。
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()] );
結果の並べ替え
並べ替えできるのは、日付フィルタを使用しているクエリのみです。
並べ替えオプションを指定しない場合、結果は降順(新しい順)に並べ替えられます。
次の表に、orderBy
パラメータでサポートされているオプションを示します。
orderBy パラメータ |
|
---|---|
MediaMetadata.creation_time desc |
メディア アイテムを降順で返します(新しいアイテムが最初) |
MediaMetadata.creation_time |
メディア アイテムを昇順で返します(古いアイテムから順に) |
次の例では、2017 年のすべてのメディア アイテムを返し、古い順と新しい順を表示します。
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 ] );