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

アルバムの識別子。指定した場合、指定したアルバム内のすべてのメディア アイテムが一覧表示されます。フィルタと組み合わせて設定することはできません。
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

フィルタ

メディア アイテムの検索に適用できるフィルタです。複数のフィルタ オプションを指定すると、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 フォト アプリでお気に入りとしてマークしたメディア アイテム。