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 を指定すると、検索結果が逆の順に表示されます。最も新しいものから古いものまで結果を表示するには、MediaMetadata.creation_time desc のように 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 スコープが使用されている場合、このフィールドは無視されます。

日付フィルタ

このフィルタでは、返されるメディアの許可期間を定義します。特定の日付と期間のセットを選択できます。

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

object (Date)

メディア アイテムと一致する日付のリストです（作成日）。1 件のリクエストにつき最大 5 件の日付を含めることができます。
ranges[]

object (DateRange)

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

日付

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

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

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

integer

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

integer

月。1 ～ 12 の範囲で指定するか、特定の月を指定しない年（0）を指定します。
day

integer

日。その年と月で有効な値を 1 ～ 31 の範囲で指定するか、日が重要でない場合に 0 に設定します。

期間

期間を指定します。どちらの日付も同じ形式にする必要があります。詳しくは Date をご覧ください。

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

object (Date)

次のいずれかの形式の開始日（範囲の一部として含まれます）。
endDate

object (Date)

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

コンテンツ フィルタ

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

含めるカテゴリのリストや除外するカテゴリのリストを指定できます。各リスト内で、カテゴリは OR で結合されます。

コンテンツ フィルタ includedContentCategories: [c1, c2, c3] は (c1 OR c2 OR c3) を含むメディア アイテムを取得します。

コンテンツ フィルタ excludedContentCategories: [c1, c2, c3] は (c1 OR c2 OR c3) を含むメディア アイテムを取得しません。

includedContentCategories : [c1, c2], excludedContentCategories: [c3, c4] のように、カテゴリを含めながら、他のものを除外することもできます。

前の例では、（c1 または c2）AND NOT（c3 または c4）を含むメディア アイテムを取得します。includedContentategories にあるカテゴリは、excludedContentCategories に含めることはできません。

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

enum (ContentCategory)

メディア アイテムの検索結果に含めるカテゴリのセット。セット内のアイテムは OR 条件で結ばれています。リクエストごとに最大 10 個の includedContentCategories があります。
excludedContentCategories[]

enum (ContentCategory)

メディア アイテムの検索結果に含まれないカテゴリのセット。セット内のアイテムは OR 条件で結ばれています。リクエストごとに最大 10 個の excludedContentCategories があります。

コンテンツ カテゴリ

定義済みコンテンツ カテゴリのセットです。

列挙型
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 ホリデー シーズンに制作されたメディア アイテム。

メディアタイプ フィルタ

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

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

enum (MediaType)

追加するメディア アイテムのタイプです。このフィールドには、1 つのメディアタイプのみを入力する必要があります。複数のメディアタイプを指定すると、エラーが発生します。

MediaType

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

列挙型
ALL_MEDIA フィルタが適用されていない場合と同様に処理されます。すべてのメディアタイプが含まれます。
VIDEO 動画と見なされるすべてのメディア アイテムです。これには、Google フォト アプリを使ってユーザーが作成した映画も含まれます。
PHOTO 写真とみなされるすべてのメディア アイテムです。これには、.bmp、.gif、.ico、.jpg（およびその他のスペル）、.tiff、.webp のほか、iOS ライブ写真、Android モーション フォト、パノラマ画像、360°写真などの特殊な写真タイプが含まれます。

特徴フィルタ

このフィルタは、メディア アイテムに含める機能を定義します。

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

enum (Feature)

メディア アイテムの検索結果に含める機能のセット。セット内のアイテムは OR で結合され、指定されたどの特徴とも一致する場合があります。

機能

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

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