Place Photos (nouveau)

Sélectionnez une plate-forme : Android iOS Service Web
Développeurs de l'Espace économique européen (EEE)

Introduction

Le service Place Photos (nouveau) est une API en lecture seule qui vous permet d'ajouter du contenu photographique de haute qualité à votre application. Place Photos (nouveau) vous donne accès à des millions de photos stockées dans la base de données Places.

Lorsque vous obtenez des informations sur un lieu à l'aide d'une requête Place Details (New), Nearby Search (New) ou Text Search (New), vous pouvez également demander des ressources photo pour le contenu photographique correspondant. Place Photos (New) vous permet ensuite d'accéder aux photos référencées et de redimensionner l'image pour qu'elle s'adapte parfaitement à votre application.

APIs Explorer vous permet d'envoyer des requêtes en direct pour vous familiariser avec l'API et ses options :

Requêtes Place Photos (nouveau)

Une requête Place Photos (New) est une requête HTTP GET envoyée à une URL au format suivant : 
https://places.googleapis.com/v1/NAME/media?key=API_KEY&PARAMETERS

Les paramètres suivants sont obligatoires :

  • NAME contient le nom de ressource de la photo.
  • API_KEY contient la clé API.
  • PARAMETERS contient le paramètre maxHeightPx, le paramètre maxWidthPx ou les deux.

La liste complète des paramètres obligatoires et facultatifs est décrite ci-dessous.

Paramètres obligatoires

Nom de la photo

Chaîne d'identification qui identifie une photo de manière unique. Les noms de photos sont renvoyés par une requête Place Details (New), Nearby Search (New) ou Text Search (New) dans la propriété name de chaque élément du tableau photos[].

Pour obtenir un exemple, consultez Obtenir le nom d'une photo.

maxHeightPx et maxWidthPx

Spécifie la hauteur et la largeur maximales prévues de l'image, en pixels. Si l'image est plus petite que les valeurs spécifiées, l'image d'origine est renvoyée. Si l'image est plus grande dans l'une ou l'autre dimension, elle sera mise à l'échelle pour correspondre à la plus petite des deux dimensions, tout en conservant son format d'origine. Les propriétés "maxheight" et "maxwidth" acceptent un entier compris entre 1 et 4 800.

Vous devez spécifier maxHeightPx, maxWidthPx, ou les deux.

Paramètres facultatifs

skipHttpRedirect

Si la valeur est false (par défaut), effectuez une redirection HTTP vers l'image pour la renvoyer. Si la valeur est true, ignorez la redirection et renvoyez une réponse JSON contenant les détails de l'image. Exemple :

{
  "name": "places/ChIJj61dQgK6j4AR4GeTYWZsKWw/photos/Aaw_FcKly0DEv3EWmDJyHiEqXIP5mowOc99lN1GzBun6KHH52AZ5fFA/media",
  "photoUri": "https://lh3.googleusercontent.com/a-/AD_cFT-b=s100-p-k-no-mo"
}

Cette option est ignorée pour les requêtes non HTTP.

Obtenir le nom d'une photo

Toutes les requêtes adressées à Place Photos (New) doivent inclure un nom de ressource photo, renvoyé dans la réponse à une requête Nearby Search (New), Text Search (New) ou Place Details (New). La réponse à ces requêtes contient un tableau photos[] si le lieu comporte du contenu photographique associé.

Chaque élément de photo[] contient les champs suivants :

  • name : chaîne contenant le nom de ressource de la photo lorsque vous effectuez une requête Photo. Cette chaîne se présente au format suivant :

    places/PLACE_ID/photos/PHOTO_RESOURCE
  • heightPx : hauteur maximale de l'image, en pixels.
  • widthPx : largeur maximale de l'image, en pixels.
  • authorAttributions[] : toutes les attributions requises. Ce champ est toujours présent, mais peut être vide.

Les photos renvoyées par Place Photos (nouveau) proviennent de plusieurs sources : elles peuvent être fournies par des propriétaires d'établissement ou par des utilisateurs. Dans la plupart des cas, ces photos peuvent être utilisées sans attribution, ou contiendront déjà l'attribution. Toutefois, si l'élément photo renvoyé inclut une valeur dans le champ authorAttributions, vous devez inclure l'attribution supplémentaire dans votre application partout où vous affichez l'image.

L'exemple suivant montre une requête Place Details (New) qui inclut photos dans le masque de champ afin que la réponse inclue le tableau photos[] :

curl -X GET \
-H 'Content-Type: application/json' -H "X-Goog-Api-Key: API_KEY" \
-H "X-Goog-FieldMask: id,displayName,photos" \
https://places.googleapis.com/v1/places/ChIJ2fzCmcW7j4AR2JzfXBBoh6E
 Vous trouverez ci-dessous un exemple de tableau photos[] dans la réponse. 
    ...
    "photos" : [
      {
        "name": "places/ChIJ2fzCmcW7j4AR2JzfXBBoh6E/photos/AUacShh3_Dd8yvV2JZMtNjjbbSbFhSv-0VmUN-uasQ2Oj00XB63irPTks0-A_1rMNfdTunoOVZfVOExRRBNrupUf8TY4Kw5iQNQgf2rwcaM8hXNQg7KDyvMR5B-HzoCE1mwy2ba9yxvmtiJrdV-xBgO8c5iJL65BCd0slyI1",
        "widthPx": 6000,
        "heightPx": 4000,
        "authorAttributions": [
          {
            "displayName": "John Smith",
            "uri": "//maps.google.com/maps/contrib/101563",
            "photoUri": "//lh3.googleusercontent.com/a-/AD_cFT-b=s100-p-k-no-mo"
          }
        ]
      },
    ...

Demander une photo d'un lieu

L'exemple de requête ci-dessous renvoie une image à l'aide de sa ressource name, en la redimensionnant de sorte qu'elle ne dépasse pas 400 pixels de hauteur et de largeur :

https://places.googleapis.com/v1/places/ChIJ2fzCmcW7j4AR2JzfXBBoh6E/photos/ATKogpeivkIjQ1FT7QmbeT33nBSwqLhdPvIWHfrG1WfmgrFjeZYpS_Ls7c7rj8jejN9QGzlx4GoAH0atSvUzATDrgrZic_tTEJdeITdWL-oG3TWi5HqZoLozrjTaxoAIxmROHfV5KXVcLeTdCC6kmZExSy0CLVIG3lAPIgmvUiewNf-ZHYE4-jXYwPQpWHJgqVosvZJ6KWEgowEA-qRAzNTu9VH6BPFqHakGQ7EqBAeYOiU8Dh-xIQC8FcBJiTi0xB4tr-MYXUaF0p_AqzAhJcDE6FAgLqG1s7EsME0o36w2nDRHA-IuoISBC3SIahINE3Xwq2FzEZE6TpNTFVfgTpdPhV8CGLeqrauHn2I6ePm-2hA8-87aO7aClXKJJVzlQ1dc_JuHz6Ks07d2gglw-ZQ3ibCTF5lMtCF9O-9JHyRQXsfuXw/media?maxHeightPx=400&maxWidthPx=400&key=API_KEY

La réponse à une requête Place Photos (nouveau) qui aboutit est une image.

Codes d'erreur

Les requêtes Place Photos (nouveau) peuvent renvoyer les codes d'erreur suivants.

Quota dépassé (403)

Si votre requête dépasse votre quota disponible, le serveur renvoie un état HTTP 403 et affiche l'image suivante pour indiquer que le quota a été dépassé :

Notification de dépassement de quota

Requête non valide (404)

Si le serveur ne parvient pas à comprendre votre requête, il renvoie l'état HTTP 400, qui indique une requête non valide. Voici les raisons les plus courantes d'une demande incorrecte :

  • Le nom de la photo envoyée n'a pas été correctement spécifié.
  • La requête n'incluait pas le paramètre maxHeightPx ni le paramètre maxWidthPx.
  • La valeur du paramètre maxHeightPx ou maxWidthtPx a été définie sur null.
  • L'name a expiré. Si name expire, envoyez une requête à Place Details (New), Nearby Search (New) ou Text Search (New) pour obtenir un nouveau name.

Trop de requêtes (429)

Google recommande de charger les photos à la demande. Si vous essayez d'afficher toutes les images d'un lieu en même temps, le serveur peut renvoyer un état HTTP 429 indiquant que vous chargez trop de photos en même temps. Si ce message d'erreur s'affiche, contactez l'assistance et demandez une augmentation du quota.

Essayer

L'API Explorer vous permet d'envoyer des exemples de requêtes pour vous familiariser avec l'API et ses options.

Pour envoyer une demande :

  1. Sélectionnez l'icône API  sur la droite de la page.
  2. Définissez le paramètre name sur : 
    places/PLACE_ID/photos/PHOTO_RESOURCE/media
  3. Définissez skipHttpRedirect sur true pour que la requête renvoie une réponse JSON. Par défaut, la requête renvoie l'image, qui ne peut pas être affichée par l'API Explorer.
  4. Sélectionnez le bouton Exécuter. Dans la boîte de dialogue, sélectionnez le compte que vous souhaitez utiliser pour envoyer la demande.

  5. Dans le panneau "API Explorer", sélectionnez l'icône plein écran  pour développer la fenêtre "API Explorer".