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 (New) est une API en lecture seule qui vous permet d'ajouter du contenu photographique de haute qualité à votre application. Place Photos (New) 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. Le service 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.

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

Requêtes Place Photos (New)

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

Identifiant de chaîne 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 un nom de photo.

maxHeightPx et maxWidthPx

Spécifie la hauteur et la largeur maximales souhaitées 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 des dimensions, elle est mise à l'échelle pour correspondre à la plus petite des deux dimensions, tout en conservant son rapport hauteur/largeur 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 un nom de 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 comme suit :

    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 il peut être vide.

Les photos renvoyées par Place Photos (New) sont extraites de plusieurs sources : elles peuvent être fournies par des propriétaires d'établissement ou par des utilisateurs. Dans la plupart des cas, les photos de lieu 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 de lieu

L'exemple de requête ci-dessous renvoie une image à l'aide de son name de ressource, en la redimensionnant pour qu'elle mesure au maximum 400 pixels de haut et de large :

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 (New) réussie est une image.

Codes d'erreur

Les requêtes Place Photos (New) 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, ce qui indique une requête non valide. Voici les raisons les plus courantes pour lesquelles une requête est non valide :

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

Trop de demandes (429)

Google recommande de charger les photos à la demande. Si vous tentez 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 de votre 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 requête :

  1. Sélectionnez l'icône d'API à 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, choisissez le compte que vous souhaitez utiliser pour envoyer la requête.

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