Le service Place Photo, qui fait partie de l'API Places, est une API en lecture seule qui vous permet d'ajouter du contenu photographique de haute qualité à votre application. Le service Place Photo 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, des références photo sont renvoyées pour le contenu photographique correspondant. Les requêtes Find Place, Nearby Search et Text Search renvoient également une référence photo unique par lieu, le cas échéant. À l'aide du service Photo, vous pouvez ensuite accéder aux photos référencées et redimensionner l'image pour qu'elle s'adapte parfaitement à votre application.
Requêtes Place Photo
Une requête de photos de lieu est une URL HTTP utilisant le format suivant :
https://maps.googleapis.com/maps/api/place/photo?parameters
Certains paramètres sont obligatoires pour lancer une requête de recherche. Comme pour toutes les URL, les différents paramètres sont séparés par une esperluette (&
). Vous trouverez ci-dessous la liste des paramètres et leurs valeurs possibles.
Required parameters
photo_reference
A string identifier that uniquely identifies a photo. Photo references are returned from either a Place Search or Place Details request.
maxheight or maxwidth
maxheight
specifies the maximum desired height, in pixels, of the image. If the image is smaller than the values specified, the original image will be returned. If the image is larger in either dimension, it will be scaled to match the smaller of the two dimensions, restricted to its original aspect ratio.maxwidth
specifies the maximum desired width, in pixels, of the image. If the image is smaller than the values specified, the original image will be returned. If the image is larger in either dimension, it will be scaled to match the smaller of the two dimensions, restricted to its original aspect ratio.Both the
maxheight
andmaxwidth
properties accept an integer between1
and1600
.You must specify either
maxheight
, ormaxwidth
, or both.
Références photo
Toutes les requêtes adressées au service Place Photo doivent inclure un photo_reference
, renvoyé dans la réponse à une requête Find Place, Nearby Search, Text Search ou Place Details. La réponse à ces requêtes contiendra un champ photos[]
si le lieu possède des photos associées.
Remarque : Le nombre de photos renvoyées varie en fonction de la requête.
- Une requête Find Place, Nearby Search ou Text Search renvoie au maximum un élément
photo
dans le tableau. - Une requête Place Details renvoie jusqu'à 10 éléments
photo
.
Chaque élément photo
contient les champs suivants:
photo_reference
: chaîne utilisée pour identifier la photo lorsque vous effectuez une requête Photo.height
: hauteur maximale de l'image.width
: largeur maximale de l'image.html_attributions[]
: contient toutes les attributions requises. Ce champ est toujours présent, mais peut être vide.
Les photos renvoyées par le service Photo sont extraites 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 l'attribution requise. Toutefois, si l'élément photo
renvoyé inclut une valeur dans le champ html_attributions
, vous devez inclure l'attribution supplémentaire dans votre application partout où vous affichez l'image.
L'exemple suivant illustre une requête Places Details:
curl "https://maps.googleapis.com/maps/api/place/details/json?placeid=ChIJcUElzOzMQQwRLuV30nMUEUM&key=YOUR_API_KEY"
Vous trouverez ci-dessous un exemple du tableau photos[]
fourni dans la réponse.
...
"photos" : [
{
"html_attributions" : [],
"height" : 853,
"width" : 1280,
"photo_reference" : "ATJ83zhSSAtkh5LTozXMhBghqubeOxnZWUV2m7Hv2tQaIzKQJgvZk9yCaEjBW0r0Zx1oJ9RF1G7oeM34sQQMOv8s2zA0sgGBiyBgvdyMxeVByRgHUXmv-rkJ2wyvNv17jyTSySm_-_6R2B0v4eKX257HOxvXlx_TSwp2NrICKrZM2d5d2P4q"
}
...
Exemple de photo de lieu
Voici un exemple de requête. Cette requête renvoie l'image référencée, en la redimensionnant pour qu'elle mesure 400 pixels de large au maximum.
https://maps.googleapis.com/maps/api/place/photo?maxwidth=400&photo_reference=ATJ83zhSSAtkh5LTozXMhBghqubeOxnZWUV2m7Hv2tQaIzKQJgvZk9yCaEjBW0r0Zx1oJ9RF1G7oeM34sQQMOv8s2zA0sgGBiyBgvdyMxeVByRgHUXmv-rkJ2wyvNv17jyTSySm_-_6R2B0v4eKX257HOxvXlx_TSwp2NrICKrZM2d5d2P4q &key=YOUR_API_KEY
Réponse relative à un lieu pour la photo
La réponse à une requête de photos de lieu valide est une image. Le type de l'image dépend de celui de la photo envoyée à l'origine.
Si votre requête dépasse votre quota disponible, le serveur renvoie un état HTTP 403 et affiche l'image ci-dessous pour indiquer que le quota a été dépassé:
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 requête non valide:
- La référence photo envoyée n'a pas été spécifiée correctement.
- La requête n'incluait pas les paramètres
maxwidth
nimaxheight
. - La valeur du paramètre
maxwidth
oumaxheight
a été définie surnull
. - La
photo_reference
a expiré. Siphoto_reference
expire, envoyez une requête à Place Details, Find Place, Nearby Search ou Text Search pour obtenir la valeurphoto_reference
mise à jour.