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

フィルタ

メディア アイテムの検索に適用できるフィルタ。複数のフィルタ オプションが指定されている場合は、互いに 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)

メディア アイテムの作成日と一致する期間のリストです。1 回のリクエストで最大 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 ～ 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 OR c2 OR c3）を含むメディア アイテムを取得します。

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

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

上記の例では、c1 または c2 を含み、c3 または c4 を含まないメディア アイテムが取得されます。includedContentategories に表示されるカテゴリを excludedContentCategories に表示することはできません。

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

enum (ContentCategory)

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

enum (ContentCategory)

メディア アイテムの検索結果に含めないカテゴリのセットです。セット内の項目は OR 結合されます。リクエストごとの excludedContentCategories の最大数は 10 です。

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 フォト アプリでお気に入りとしてマークしたメディア アイテムです。