Place Photos

Il servizio Place Photo, che fa parte dell'API Places, è un'API di sola lettura che ti consente di aggiungere contenuti fotografici di alta qualità alla tua applicazione. Il servizio Foto del luogo ti consente di accedere ai milioni di foto memorizzate nel database di Places. Quando ottieni informazioni sui luoghi utilizzando una richiesta Place Details, vengono restituiti i riferimenti alle foto per i contenuti fotografici pertinenti. Le richieste Trova luogo, Ricerca nelle vicinanze e Ricerca di testo restituiscono anche un singolo riferimento fotografico per luogo, se pertinente. Utilizzando il servizio Foto, puoi accedere alle foto a cui fai riferimento e ridimensionare l'immagine alle dimensioni ottimali per la tua applicazione.

Richieste di foto del luogo

Una richiesta di foto di un luogo è un URL HTTP del seguente tipo:

https://maps.googleapis.com/maps/api/place/photo?parameters

Per avviare una richiesta di ricerca sono necessari alcuni parametri. Come standard negli URL, tutti i parametri sono separati utilizzando il carattere e commerciale (&). Di seguito è elencato l'elenco dei parametri e dei relativi valori possibili.

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 and maxwidth properties accept an integer between 1 and 1600.

    You must specify either maxheight, or maxwidth, or both.

Riferimenti fotografici

Tutte le richieste al servizio Foto del luogo devono includere un valore photo_reference, restituito nella risposta a una richiesta Trova un luogo, Ricerca nelle vicinanze, Ricerca di testo o Dettagli luogo. La risposta a queste richieste conterrà un campo photos[] se il luogo ha contenuti fotografici correlati.

Nota:il numero di foto restituite varia in base alla richiesta.

  • Una richiesta di ricerca di luoghi, ricerca nelle vicinanze o ricerca di testo restituisce al massimo un elementophoto nell'array.
  • Una richiesta Places Details restituisce fino a dieci elementi photo.

Ogni elemento photo contiene i seguenti campi:

  • photo_reference: una stringa utilizzata per identificare la foto quando effettui una richiesta di foto.
  • height: l'altezza massima dell'immagine.
  • width: la larghezza massima dell'immagine.
  • html_attributions[]: contiene le eventuali attribuzioni richieste. Questo campo sarà sempre presente, ma potrebbe essere vuoto.

Le foto restituite dal servizio Foto provengono da varie origini, tra cui foto inviate da proprietari di attività e utenti. Nella maggior parte dei casi, queste foto possono essere utilizzate senza attribuzione o l'attribuzione richiesta sarà inclusa nell'immagine. Tuttavia, se l'elemento photo restituito include un valore nel campo html_attributions, devi includere l'attribuzione aggiuntiva nella tua applicazione ovunque venga visualizzata l'immagine.

L'esempio seguente mostra una richiesta Places 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 foto del luogo

Di seguito è riportato un esempio di richiesta. Questa richiesta restituisce l'immagine a cui si fa riferimento, ridimensionandola in modo che abbia una larghezza massima di 400 pixel.

https://maps.googleapis.com/maps/api/place/photo?maxwidth=400&photo_reference=ATJ83zhSSAtkh5LTozXMhBghqubeOxnZWUV2m7Hv2tQaIzKQJgvZk9yCaEjBW0r0Zx1oJ9RF1G7oeM34sQQMOv8s2zA0sgGBiyBgvdyMxeVByRgHUXmv-rkJ2wyvNv17jyTSySm_-_6R2B0v4eKX257HOxvXlx_TSwp2NrICKrZM2d5d2P4q&key=YOUR_API_KEY

Risposta a Place Photo

La risposta di una richiesta di foto di un luogo andata a buon fine è un'immagine. Il tipo di immagine dipende dal tipo di foto inviata inizialmente.

Se la tua richiesta supera la quota disponibile, il server restituisce un stato HTTP 403 e mostra l'immagine seguente per indicare che la quota è stata superata:

Immagine quota superata

Se il server non è in grado di comprendere la richiesta, restituisce lo stato HTTP 400, che indica una richiesta non valida. Ecco alcuni dei motivi più comuni per una richiesta non valida:

  • Il riferimento alla foto inviato non è stato specificato correttamente.
  • La richiesta non includeva i parametri maxwidth o maxheight.
  • Il valore del parametro maxwidth o maxheight è stato impostato su null.
  • photo_reference è scaduto. Se photo_reference scade, invia una richiesta a Dettagli dei luoghi, Trova un luogo, Ricerca nelle vicinanze o Ricerca di testo per ottenere il valore aggiornato di photo_reference.