Method: mediaItems.search

ユーザーの Google フォト ライブラリ内のメディア アイテムを検索します。フィルタを設定しない場合は、ユーザーのライブラリ内にあるすべてのメディア アイテムが返されます。アルバムを設定すると、指定されたアルバム内にあるすべてのメディア アイテムが返されます。フィルタを指定すると、ユーザーのライブラリ内にある、フィルタに一致するメディア アイテムが表示されます。アルバムとフィルタの両方を設定すると、リクエストはエラーになります。

HTTP リクエスト

POST https://photoslibrary.googleapis.com/v1/mediaItems:search

この URL は gRPC Transcoding 構文を使用します。

リクエストの本文

リクエストの本文には、次の構造のデータが含まれます。

JSON 表現 
{
  "albumId": string,
  "pageSize": integer,
  "pageToken": string,
  "filters": {
    object (Filters)
  },
  "orderBy": string
}
フィールド
albumId

string

アルバムの ID。設定すると、指定したアルバム内にあるすべてのメディア アイテムがリストされます。フィルタと組み合わせて設定することはできません。
pageSize

integer

レスポンスで返されるメディア アイテムの最大数。指定した数よりも少ないメディア アイテムが返される場合があります。デフォルトの pageSize は 25、最大値は 100 です。
pageToken

string

結果の次のページを取得するための連続トークン。これをリクエストに追加すると、pageToken の後に行が返されます。pageToken は、searchMediaItems リクエストに対するレスポンスの nextPageToken パラメータで返される値である必要があります。
filters

object (Filters)

リクエストに適用するフィルタ。albumId と組み合わせて設定することはできません。
orderBy

string

検索結果の並べ替え順序を指定するオプション フィールド。orderBy フィールドは、dateFilter が使用されている場合にのみ機能します。このフィールドが指定されていない場合、結果は creationTime で新しい順に表示されます。MediaMetadata.creation_time を指定すると、検索結果は古い順に表示されます。結果を新しいものから最も古いものへと表示するには、desc 引数を MediaMetadata.creation_time desc のように指定します。

このパラメータで使用できる追加のフィルタは includeArchivedMedia と excludeNonAppCreatedData のみです。他のフィルタはサポートされていません。

レスポンスの本文

検索パラメータに一致するメディア アイテムのリスト。

成功した場合、レスポンスの本文には次の構造のデータが含まれます。

JSON 表現 
{
  "mediaItems": [
    {
      object (MediaItem)
    }
  ],
  "nextPageToken": string
}
フィールド
mediaItems[]

object (MediaItem)

出力専用。検索パラメータに一致するメディア アイテムのリスト。
nextPageToken

string

出力専用。このトークンを使用して、メディア アイテムの次のセットを取得します。この変数の存在は、次のリクエストでより多くのメディア アイテムが利用可能であることを示す唯一の確実な指標です。

認可スコープ

次の OAuth スコープのいずれかが必要です。

  • https://www.googleapis.com/auth/photoslibrary
  • https://www.googleapis.com/auth/photoslibrary.readonly
  • https://www.googleapis.com/auth/photoslibrary.readonly.appcreateddata
  • https://www.googleapis.com/auth/photoslibrary.readonly.originals

フィルタ

メディア アイテムの検索に適用できるフィルタです。複数のフィルタ オプションを指定すると、AND 条件として扱われます。

JSON 表現 
{
  "dateFilter": {
    object (DateFilter)
  },
  "contentFilter": {
    object (ContentFilter)
  },
  "mediaTypeFilter": {
    object (MediaTypeFilter)
  },
  "featureFilter": {
    object (FeatureFilter)
  },
  "includeArchivedMedia": boolean,
  "excludeNonAppCreatedData": boolean
}
フィールド
dateFilter

object (DateFilter)

作成日に基づいてメディア アイテムをフィルタします。
contentFilter

object (ContentFilter)

コンテンツに基づいてメディア アイテムをフィルタします。
mediaTypeFilter

object (MediaTypeFilter)

メディアのタイプに基づいてメディア アイテムをフィルタします。
featureFilter

object (FeatureFilter)

機能に基づいてメディア アイテムをフィルタします。
includeArchivedMedia

boolean

設定すると、ユーザーがアーカイブしたメディア アイテムが結果に含まれます。デフォルトは false です（アーカイブされたメディア アイテムは含まれません）。
excludeNonAppCreatedData

boolean

設定すると、このアプリ以外で作成されたメディア アイテムが結果から除外されます。デフォルトは false です（すべてのメディア アイテムが返されます）。photoslibrary.readonly.appcreateddata スコープが使用されている場合、このフィールドは無視されます。

DateFilter

このフィルタは、返されるメディアに許可される日付または期間を定義します。特定の日付のセットと期間のセットを指定できます。メディア アイテムがキャプチャされた日付を指定するメタデータなしでアップロードされたメディア アイテムは、日付フィルタを使用したクエリでは返されません。この場合、Google フォト サーバーへのアップロード時間はフォールバックとして使用されません。

JSON 表現 
{
  "dates": [
    {
      object (Date)
    }
  ],
  "ranges": [
    {
      object (DateRange)
    }
  ]
}
フィールド
dates[]

object (Date)

メディア アイテムの作成日と一致する日付のリスト。リクエストごとに最大 5 つの日付を指定できます。
ranges[]

object (DateRange)

メディア アイテムの作成日と一致する期間のリスト。リクエストごとに最大 5 つの期間を指定できます。

日付

カレンダーの日付全体を表します。月と年のみが重要な場合（2018 年 12 月全体など）は、day を 0 に設定します。年のみが重要である場合（2018 年全体など）は、day と month を 0 に設定します。日と月のみ（記念日や誕生日など）が重要な場合は、year を 0 に設定します。

サポート対象外: すべての値を 0 に設定する、month のみを 0 に設定する、day と year の両方を同時に 0 に設定すること。

JSON 表現 
{
  "year": integer,
  "month": integer,
  "day": integer
}
フィールド
year

integer

その日付の年。1～9999、または年のない日付を指定する場合は 0 にする必要があります。
month

integer

1 年の中の月。1～12、または月と日のない年を指定する場合は 0 にする必要があります。
day

integer

日。1 ～ 31 を指定し、対象の年月に対して有効な日である必要があります。特定の日を指定しない年と月を表す場合は 0 を指定します。

DateRange

日付の範囲を定義します。開始日と終了日は同じ形式にする必要があります。詳しくは Date をご覧ください。

JSON 表現 
{
  "startDate": {
    object (Date)
  },
  "endDate": {
    object (Date)
  }
}
フィールド
startDate

object (Date)

開始日（範囲の一部として含まれる）。記載されているいずれかの形式で指定します。
endDate

object (Date)

終了日（期間の一部に含まれます）。開始日と同じ形式で指定する必要があります。

ContentFilter

このフィルタを使用すると、コンテンツ タイプに基づいてメディア アイテムを返すことができます。

含めるカテゴリのリストや除外するカテゴリのリストを指定できます。各リストでは、カテゴリは OR 条件として処理されます。

コンテンツ フィルタを includedContentCategories: [c1, c2, c3] と指定すると、c1、c2、c3 のいずれかを含むメディア アイテムが取得されます。

コンテンツ フィルタを excludedContentCategories: [c1, c2, c3] と指定すると、c1、c2、c3 のいずれかを含むメディア アイテムは除外されます。

一部のカテゴリを含み、同時に一部のカテゴリを除外することもできます。その場合、includedContentCategories: [c1, c2] と excludedContentCategories: [c3, c4] のように指定します。

前の例では、c1、c2 のいずれかを含み、c3、c4 のどちらも含まないメディア アイテムが取得されます。includedContentategories に指定したカテゴリを excludedContentCategories に指定することはできません。

JSON 表現 
{
  "includedContentCategories": [
    enum (ContentCategory)
  ],
  "excludedContentCategories": [
    enum (ContentCategory)
  ]
}
フィールド
includedContentCategories[]

enum (ContentCategory)

メディア アイテムの検索結果に含めるカテゴリのセット。セット内のアイテムは OR で結合されます。リクエストごとに最大 10 個の includedContentCategories を指定できます。
excludedContentCategories[]

enum (ContentCategory)

メディア アイテムの検索結果から除外するカテゴリのセット。セット内のアイテムは OR で結合されます。リクエストごとに最大 10 個の excludedContentCategories を指定できます。

ContentCategory

事前定義済みのフィルタ可能なコンテンツ カテゴリのセットです。

列挙型
NONE デフォルトのコンテンツ カテゴリ。フィルタで他のカテゴリが使用されている場合、このカテゴリは無視されます。
LANDSCAPES 風景を含むメディア アイテム。
RECEIPTS 領収書を含むメディア アイテム。
CITYSCAPES 都市の景観を含むメディア アイテム。
LANDMARKS ランドマークを含むメディア アイテム。
SELFIES 自撮り写真であるメディア アイテム。
PEOPLE 人物を含むメディア アイテム。
PETS ペットを含むメディア アイテム。
WEDDINGS 結婚式のメディア アイテム。
BIRTHDAYS 誕生日のメディア アイテム。
DOCUMENTS ドキュメントを含むメディア アイテム。
TRAVEL 旅行中に撮影したメディア アイテム。
ANIMALS 動物を含むメディア アイテム。
FOOD 食べ物を含むメディア アイテム。
SPORT スポーツ イベントのメディア アイテム。
NIGHT 夜に撮影されたメディア アイテム。
PERFORMANCES パフォーマンスのメディア アイテム。
WHITEBOARDS ホワイトボードを含むメディア アイテム。
SCREENSHOTS スクリーンショットのメディア アイテム。
UTILITY 実用性が高いと考えられるメディア アイテムです。ドキュメント、スクリーンショット、ホワイトボードなどが含まれますが、これらに限定されません。
ARTS アートを含むメディア アイテム。
CRAFTS 工作を含むメディア アイテム。
FASHION ファッションに関連するメディア アイテム。
HOUSES 家を含むメディア アイテム。
GARDENS 庭を含むメディア アイテム。
FLOWERS 花を含むメディア アイテム。
HOLIDAYS 休日に撮影されたメディア アイテム。

MediaTypeFilter

このフィルタでは、返されるメディア アイテムのタイプを定義します（動画や写真など）。サポートされるメディアタイプは 1 つのみです。

JSON 表現 
{
  "mediaTypes": [
    enum (MediaType)
  ]
}
フィールド
mediaTypes[]

enum (MediaType)

含めるメディア アイテムのタイプ。このフィールドにはメディアタイプを 1 つだけ指定できます。複数のメディアタイプを指定するとエラーが返されます。

MediaType

検索可能なメディアタイプのセットです。

列挙型
ALL_MEDIA フィルタが適用されていない場合と同様に扱われます。すべてのメディアタイプが含まれます。
VIDEO 動画と見なされるすべてのメディア アイテム。ユーザーが Google フォト アプリを使用して作成したムービーも含まれます。
PHOTO 写真と見なされるすべてのメディア アイテム。.bmp、.gif、.ico、.jpg（他の綴りの場合も含む）、.tiff、.webp、特別な写真のタイプ（iOS の Live Photos、Android のモーション フォト、パノラマ、360° 写真など）が含まれます。

FeatureFilter

このフィルタでは、メディア アイテムに含まれている必要がある機能を定義します。

JSON 表現 
{
  "includedFeatures": [
    enum (Feature)
  ]
}
フィールド
includedFeatures[]

enum (Feature)

メディア アイテムの検索結果に含める機能のセット。セット内のアイテムは OR 条件として扱われ、指定された機能のいずれかに一致すると取得されます。

機能

フィルタできる一連の特徴。

列挙型
NONE フィルタが適用されていない場合と同様に扱われます。すべての機能が含まれます。
FAVORITES ユーザーが Google フォト アプリでお気に入りとしてマークしたメディア アイテム。