Method: mediaItems.search

Restez organisé à l'aide des collections Enregistrez et classez les contenus selon vos préférences.

Recherche des éléments multimédias dans la bibliothèque Google Photos d'un utilisateur. Si aucun filtre n'est défini, tous les éléments multimédias de la bibliothèque de l'utilisateur sont renvoyés. Si un album est défini, tous les éléments multimédias de l'album spécifié sont renvoyés. Si des filtres sont spécifiés, les éléments multimédias correspondant aux filtres de la bibliothèque de l'utilisateur sont listés. Si vous définissez à la fois l'album et les filtres, une erreur est générée.

Requête HTTP :

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

L'URL utilise la syntaxe de transcodage gRPC.

Corps de la requête

Le corps de la requête contient des données présentant la structure suivante :

Représentation JSON
{
  "albumId": string,
  "pageSize": integer,
  "pageToken": string,
  "filters": {
    object (Filters)
  },
  "orderBy": string
}
Champs
albumId

string

Identifiant d'un album. Si ce champ est renseigné, répertorie tous les éléments multimédias de l'album spécifié. Ce paramètre ne peut être défini avec aucun filtre.

pageSize

integer

Nombre maximal d'éléments multimédias à renvoyer dans la réponse. Le nombre d'éléments multimédias pouvant être renvoyés est inférieur au nombre spécifié. La valeur par défaut de pageSize est 25, et la valeur maximale est de 100.

pageToken

string

Jeton de continuité pour obtenir la page de résultats suivante. Si vous l'ajoutez à la requête, les lignes qui suivent pageToken sont renvoyées. pageToken doit être la valeur renvoyée dans le paramètre nextPageToken dans la réponse à la requête searchMediaItems.

filters

object (Filters)

Filtres à appliquer à la requête. Ne peut pas être défini avec un albumId.

orderBy

string

Champ facultatif permettant de spécifier l'ordre de tri des résultats de recherche. Le champ orderBy ne fonctionne que si un champ dateFilter est utilisé. Lorsque ce champ n'est pas spécifié, les résultats s'affichent en premier, les plus anciens en dernier, en fonction de leur creationTime. Si vous indiquez MediaMetadata.creation_time, les résultats de recherche s'affichent dans l'ordre inverse : par ordre décroissant. Pour afficher les résultats les plus récents en premier, puis en dernier, ajoutez l'argument desc comme suit: MediaMetadata.creation_time desc.

Les seuls filtres supplémentaires que vous pouvez utiliser avec ce paramètre sont includeArchivedMedia et excludeNonAppCreatedData. Aucun autre filtre n'est accepté.

Corps de la réponse

Si la requête aboutit, le corps de la réponse contient des données qui ont la structure suivante :

Liste des éléments multimédias correspondant aux paramètres de recherche.

Représentation JSON
{
  "mediaItems": [
    {
      object (MediaItem)
    }
  ],
  "nextPageToken": string
}
Champs
mediaItems[]

object (MediaItem)

Uniquement en sortie. Liste des éléments multimédias correspondant aux paramètres de recherche.

nextPageToken

string

Uniquement en sortie. Utilisez ce jeton pour obtenir le prochain ensemble d'éléments multimédias. Sa présence est le seul indicateur fiable d'un plus grand nombre d'éléments multimédias disponibles dans la demande suivante.

Champs d'application des autorisations

Nécessite l'un des champs d'application OAuth suivants :

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

Filtres

Filtres applicables à la recherche d'éléments multimédias. Si plusieurs options de filtre sont spécifiées, elles sont traitées comme ET.

Représentation JSON
{
  "dateFilter": {
    object (DateFilter)
  },
  "contentFilter": {
    object (ContentFilter)
  },
  "mediaTypeFilter": {
    object (MediaTypeFilter)
  },
  "featureFilter": {
    object (FeatureFilter)
  },
  "includeArchivedMedia": boolean,
  "excludeNonAppCreatedData": boolean
}
Champs
dateFilter

object (DateFilter)

Filtre les éléments multimédias en fonction de leur date de création.

contentFilter

object (ContentFilter)

Filtre les éléments multimédias en fonction de leur contenu.

mediaTypeFilter

object (MediaTypeFilter)

Filtre les éléments multimédias en fonction du type de contenu.

featureFilter

object (FeatureFilter)

Filtre les éléments multimédias en fonction de leurs caractéristiques.

includeArchivedMedia

boolean

Si ce champ est défini, les résultats incluent les éléments multimédias archivés par l'utilisateur. La valeur par défaut est "false" (les éléments multimédias archivés ne sont pas inclus).

excludeNonAppCreatedData

boolean

Si ce champ est défini, les éléments multimédias qui n'ont pas été créés par cette application sont exclus. La valeur par défaut est "false" (tous les éléments multimédias sont renvoyés). Ce champ est ignoré si le champ d'application photoslibrary.readonly.appcreateddata est utilisé.

Filtre de date

Ce filtre définit les dates autorisées ou les plages de dates pour le contenu multimédia renvoyé. Vous pouvez choisir un ensemble de dates et de plages de dates spécifiques. Les éléments multimédias importés sans métadonnées spécifiant la date de capture de l'élément multimédia ne seront pas renvoyés dans les requêtes utilisant des filtres de date. Dans ce cas, l'heure d'importation du serveur Google Photos n'est pas utilisée en remplacement.

Représentation JSON
{
  "dates": [
    {
      object (Date)
    }
  ],
  "ranges": [
    {
      object (DateRange)
    }
  ]
}
Champs
dates[]

object (Date)

Liste des dates qui correspondent à la date de création des éléments multimédias. Vous pouvez inclure jusqu'à cinq dates par demande.

ranges[]

object (DateRange)

Liste de plages de dates qui correspondent à la date de création des éléments multimédias. Vous pouvez inclure jusqu'à cinq plages de dates par demande.

Date

Représente une date entière. Définissez day sur 0 lorsque seuls le mois et l'année sont significatifs, par exemple en décembre 2018. Définissez day et month sur 0 si seule l'année est significative, par exemple toute l'année 2018. Définissez year sur 0 lorsque seuls le jour et le mois sont significatifs (un anniversaire ou un anniversaire, par exemple).

Non compatible: définissez toutes les valeurs sur 0, uniquement month sur 0, ou day et year sur 0 en même temps.

Représentation JSON
{
  "year": integer,
  "month": integer,
  "day": integer
}
Champs
year

integer

Année de la date. La valeur doit être comprise entre 1 et 9999, ou égale à 0 pour indiquer une date sans année.

month

integer

Mois d'une année. La valeur doit être comprise entre 1 et 12, ou égale à 0 pour indiquer une année sans mois ni jour.

day

integer

Jour du mois. La valeur doit être comprise entre 1 et 31, et valide pour l'année et le mois, ou égale à 0 si vous spécifiez une année/mois où le jour n'est pas significatif.

DateRange

Définit une plage de dates. Les deux dates doivent être au même format. Pour en savoir plus, consultez Date.

Représentation JSON
{
  "startDate": {
    object (Date)
  },
  "endDate": {
    object (Date)
  }
}
Champs
startDate

object (Date)

Date de début (incluse dans la plage) dans l'un des formats décrits.

endDate

object (Date)

Date de fin (incluse dans la plage) Il doit être indiqué dans le même format que la date de début.

Filtre de contenu

Ce filtre vous permet de renvoyer des éléments multimédias en fonction du type de contenu.

Vous pouvez spécifier une liste de catégories à inclure et/ou une liste de catégories à exclure. Dans chaque liste, les catégories sont combinées avec un OR.

Le filtre de contenu includedContentCategories [c1, c2, c3] permet d'obtenir les éléments multimédias qui contiennent (c1 OR c2 OR c3).

Le filtre de contenu excludedContentCategories [c1, c2, c3] n'obtient PAS les éléments multimédias qui contiennent (c1 OR c2 OR c3).

Vous pouvez également inclure certaines catégories tout en excluant d'autres, comme dans cet exemple: includedContentCategories: [c1, c2], excludedContentCategories: [c3, c4]

L'exemple précédent obtient les éléments multimédias qui contiennent (c1 OR c2) ET PAS (c3 OR c4). Une catégorie qui figure dans includedContentategories ne doit pas apparaître dans excludedContentCategories.

Représentation JSON
{
  "includedContentCategories": [
    enum (ContentCategory)
  ],
  "excludedContentCategories": [
    enum (ContentCategory)
  ]
}
Champs
includedContentCategories[]

enum (ContentCategory)

Ensemble de catégories à inclure dans les résultats de recherche d'éléments multimédias. Les éléments de l'ensemble sont associés à l'opérateur OR. Le nombre de requêtes est limité à 10 includedContentCategories par requête.

excludedContentCategories[]

enum (ContentCategory)

Ensemble de catégories à ne pas inclure dans les résultats de recherche d'éléments multimédias. Les éléments de l'ensemble sont associés à l'opérateur OR. Le nombre de requêtes est limité à 10 excludedContentCategories par requête.

Catégorie de contenu

Il s'agit d'un ensemble de catégories de contenu prédéfinies que vous pouvez filtrer.

Enums
NONE Catégorie de contenu par défaut. Cette catégorie est ignorée lorsqu'une autre catégorie est utilisée dans le filtre.
LANDSCAPES Éléments multimédias contenant des paysages.
RECEIPTS Éléments multimédias contenant des reçus
CITYSCAPES Éléments multimédias contenant des paysages urbains.
LANDMARKS Éléments multimédias contenant des points de repère
SELFIES Éléments multimédias qui sont des selfies
PEOPLE Éléments multimédias contenant des personnes.
PETS Contenus multimédias montrant des animaux de compagnie.
WEDDINGS Contenus multimédias pour les mariages
BIRTHDAYS Éléments multimédias des anniversaires
DOCUMENTS Éléments multimédias contenant des documents
TRAVEL Éléments multimédias pris pendant un voyage.
ANIMALS Éléments multimédias contenant des animaux
FOOD Contenus multimédias contenant de la nourriture
SPORT Éléments multimédias issus d'événements sportifs
NIGHT Éléments multimédias pris la nuit.
PERFORMANCES Éléments multimédias issus des spectacles.
WHITEBOARDS Éléments multimédias contenant des tableaux blancs
SCREENSHOTS Éléments multimédias correspondant à des captures d'écran
UTILITY Éléments multimédias considérés comme utiles. Cela inclut, sans s'y limiter, les documents, captures d'écran, tableaux blancs, etc.
ARTS Éléments multimédias contenant des œuvres d'art
CRAFTS Contenus multimédias contenant des objets d'artisanat
FASHION Éléments multimédias liés à la mode.
HOUSES Éléments multimédias contenant des maisons.
GARDENS Éléments multimédias contenant des jardins.
FLOWERS Éléments multimédias contenant des fleurs
HOLIDAYS Éléments multimédias de vacances

MediaTypeFilter

Ce filtre définit le type d'éléments multimédias à renvoyer (par exemple, des vidéos ou des photos). Un seul type de support est accepté.

Représentation JSON
{
  "mediaTypes": [
    enum (MediaType)
  ]
}
Champs
mediaTypes[]

enum (MediaType)

Types d'éléments multimédias à inclure. Ce champ ne doit contenir qu'un seul type de support. Si vous spécifiez plusieurs types de médias, une erreur est générée.

MediaType

Ensemble des types de supports pouvant faire l'objet d'une recherche.

Enums
ALL_MEDIA Traité comme si aucun filtre n'était appliqué. Tous les types de support sont inclus.
VIDEO Tous les éléments multimédias considérés comme des vidéos. y compris les films que l'utilisateur a créés à l'aide de l'application Google Photos.
PHOTO Tous les éléments multimédias considérés comme des photos. Cela inclut les fichiers .bmp, .gif, .ico, .jpg (et d'autres orthographes), .tiff, .webp et les types de photos spéciaux tels que les photos en direct sur iOS, les photos animées sur Android, les panoramas et les photo-sphères.

Filtre de caractéristiques

Ce filtre définit les fonctionnalités que les éléments multimédias doivent avoir.

Représentation JSON
{
  "includedFeatures": [
    enum (Feature)
  ]
}
Champs
includedFeatures[]

enum (Feature)

Ensemble de fonctionnalités à inclure dans les résultats de recherche d'éléments multimédias. Les éléments de l'ensemble sont associés à l'opérateur OR et peuvent correspondre à n'importe lequel des éléments géographiques spécifiés.

Fonctionnalité

Ensemble de fonctionnalités que vous pouvez filtrer.

Enums
NONE Traité comme si aucun filtre n'était appliqué. Toutes les fonctionnalités sont incluses.
FAVORITES Éléments multimédias que l'utilisateur a marqués comme favoris dans l'application Google Photos.