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 スコープが使用されている場合、このフィールドは無視されます。

日付フィルタ

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

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

object (Date)

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

object (DateRange)

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

日付

カレンダーの日付全体を表します。月と年のみが重要な場合（たとえば、2018 年 12 月中など）は、day を 0 に設定します。1 年のみが重要な場合（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 にする必要があります。

期間

日付の範囲を定義します。両方の日付は同じ形式にする必要があります。詳しくは 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 OR c2) AND NOT (c3 OR 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 休日に撮影されたメディア アイテム。

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°写真など）が含まれます。

機能フィルタ

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

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

enum (Feature)

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

機能

フィルタの対象となる機能のセット。

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