Il servizio Place Photo, parte dell'API Places, è un'API di sola lettura che consente di aggiungere contenuti fotografici di alta qualità alla tua applicazione. Il servizio Place Photo ti dà accesso a milioni di foto memorizzate nel database di Places. Quando ricevi informazioni su un luogo utilizzando una richiesta Place Details, vengono restituiti riferimenti fotografici a contenuti fotografici pertinenti. Le richieste Trova luogo, Ricerca nelle vicinanze e Ricerca testuale restituiscono anche un solo riferimento foto per luogo, se pertinente. Tramite il servizio Foto puoi accedere alle foto di riferimento e ridimensionarle alle dimensioni ottimali per la tua applicazione.
Richieste foto luogo
Una richiesta Place Photo è un URL HTTP con il seguente formato:
https://maps.googleapis.com/maps/api/place/photo?parameters
Per avviare una richiesta di ricerca sono necessari alcuni parametri. Come avviene normalmente negli URL, tutti i parametri vengono separati mediante il carattere della e commerciale (&
). L'elenco dei parametri e dei relativi valori possibili è riportato di seguito.
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.
Riferimenti fotografici
Tutte le richieste al servizio Foto del luogo devono includere un photo_reference
,
restituito in risposta a una richiesta Trova luogo, Ricerca nelle vicinanze, Ricerca testuale o
Dettagli luogo. La risposta a queste richieste conterrà un campo photos[]
se il
luogo presenta contenuti fotografici correlati.
Nota: il numero di foto restituite varia a seconda della richiesta.
- Una richiesta Trova luogo, Ricerca nelle vicinanze o Ricerca testuale restituisce al massimo un elemento
photo
nell'array. - Una richiesta Place Details restituisce fino a dieci elementi
photo
.
Ogni elemento photo
contiene i seguenti campi:
photo_reference
: una stringa utilizzata per identificare la foto quando esegui una richiesta di foto.height
: l'altezza massima dell'immagine.width
: la larghezza massima dell'immagine.html_attributions[]
: contiene le attribuzioni obbligatorie. Questo campo sarà sempre presente, ma potrebbe essere vuoto.
Le foto restituite dal servizio Foto provengono da diverse località, tra cui i proprietari delle attività e le foto fornite dagli utenti. Nella maggior parte dei casi, queste foto possono essere utilizzate senza attribuzione o avranno l'attribuzione richiesta inclusa all'interno dell'immagine. Tuttavia, se l'elemento photo
restituito include un valore nel campo html_attributions
, devi includere l'attribuzione aggiuntiva nella tua applicazione ovunque mostri l'immagine.
Nell'esempio seguente viene mostrata una richiesta Place Details:
curl "https://maps.googleapis.com/maps/api/place/details/json?placeid=ChIJcUElzOzMQQwRLuV30nMUEUM&key=YOUR_API_KEY"
Di seguito è riportato un esempio dell'array photos[]
nella risposta.
...
"photos" : [
{
"html_attributions" : [],
"height" : 853,
"width" : 1280,
"photo_reference" : "ATJ83zhSSAtkh5LTozXMhBghqubeOxnZWUV2m7Hv2tQaIzKQJgvZk9yCaEjBW0r0Zx1oJ9RF1G7oeM34sQQMOv8s2zA0sgGBiyBgvdyMxeVByRgHUXmv-rkJ2wyvNv17jyTSySm_-_6R2B0v4eKX257HOxvXlx_TSwp2NrICKrZM2d5d2P4q"
}
...
Esempio di Place Photo
Di seguito è riportata una richiesta di esempio. La richiesta restituirà l'immagine di riferimento, ridimensionandola in modo che abbia una larghezza di massimo 400 pixel.
https://maps.googleapis.com/maps/api/place/photo?maxwidth=400&photo_reference=ATJ83zhSSAtkh5LTozXMhBghqubeOxnZWUV2m7Hv2tQaIzKQJgvZk9yCaEjBW0r0Zx1oJ9RF1G7oeM34sQQMOv8s2zA0sgGBiyBgvdyMxeVByRgHUXmv-rkJ2wyvNv17jyTSySm_-_6R2B0v4eKX257HOxvXlx_TSwp2NrICKrZM2d5d2P4q &key=YOUR_API_KEY
Risposta per foto del luogo
La risposta a una richiesta di Place Photo approvata sarà un'immagine. Il tipo di immagine dipende dal tipo di foto inviata inizialmente.
Se la richiesta supera la quota disponibile, il server restituisce uno stato HTTP 403 e visualizza l'immagine seguente per indicare che la quota è stata superata:
Se il server non è in grado di comprendere la richiesta, restituisce lo stato HTTP 400, che indica una richiesta non valida. I motivi più comuni di una richiesta non valida includono:
- Il riferimento della foto inviato non è stato specificato correttamente.
- La richiesta non includeva i parametri
maxwidth
omaxheight
. - Il valore del parametro
maxwidth
omaxheight
è stato impostato sunull
. - L'offerta
photo_reference
è scaduta. Sephoto_reference
scade, invia una richiesta a Dettagli luogo, Trova luogo, Ricerca nelle vicinanze o Ricerca testuale per ricevere il valore aggiornato diphoto_reference
.