Il servizio Place Photo (New) (Foto di luogo (nuova)) è un'API di sola lettura che ti consente di aggiungere contenuti fotografici di alta qualità alla tua applicazione. Il servizio Place Photo ti dà accesso a milioni di foto archiviate nel database di Places.
Quando ricevi le informazioni sui luoghi tramite una richiesta Dettagli luogo, Ricerca nelle vicinanze o Ricerca testuale, puoi anche richiedere risorse fotografiche per i contenuti fotografici pertinenti. Utilizzando il servizio Foto, puoi quindi accedere alle foto a cui viene fatto riferimento e ridimensionare l'immagine alle dimensioni ottimali per la tua applicazione.
Explorer API ti consente di effettuare richieste in tempo reale in modo da acquisire familiarità con l'API e le relative opzioni:
Prova!Effettua richieste di foto
Una richiesta Place Photo è una richiesta HTTP GET a un URL nel modulo:https://places.googleapis.com/v1/NAME/media?key=API_KEY&PARAMETERS
Dove sono richiesti i seguenti parametri:
- NAME contiene il nome risorsa della foto.
- API_KEY contiene la chiave API.
- PARAMETERS contiene il parametro
maxHeightPx
, il parametromaxWidthPx
o entrambi.
Di seguito è riportato l'elenco completo dei parametri obbligatori e facoltativi.
Parametri obbligatori
Nome foto
Un identificatore di stringa che identifica in modo univoco una foto. I nomi delle foto vengono restituiti da una richiesta Dettagli luogo (nuovo), Ricerca nelle vicinanze (nuova) o Ricerca testuale (Nuova) nella proprietà name
di ogni elemento dell'array photos[]
.
Per un esempio, vedi Ottenere un nome per una foto.
maxAltezzaPx e maxLarghezzaPx
Specifica l'altezza e la larghezza massima, in pixel, dell'immagine. Se l'immagine è più piccola rispetto ai valori specificati, verrà restituita l'immagine originale. Se l'immagine è più grande in entrambe le dimensioni, verrà ridimensionata in modo da corrispondere alla dimensione più piccola tra le due, limitatamente alle proporzioni originali. Entrambe le proprietà maxheight e maxwidth accettano un numero intero compreso tra 1 e 4800.
Devi specificare maxHeightPx
o maxWidthPx
oppure entrambi.
Parametri facoltativi
skipHttpRedirect
Se il valore è false
(impostazione predefinita), esegui un reindirizzamento HTTP all'immagine per restituirla.
Se true
, ignora il reindirizzamento e restituisci una risposta JSON contenente l'errore dell'immagine.
Ad esempio:
{ "name": "places/ChIJj61dQgK6j4AR4GeTYWZsKWw/photos/Aaw_FcKly0DEv3EWmDJyHiEqXIP5mowOc99lN1GzBun6KHH52AZ5fFA/media", "photoUri": "https://lh3.googleusercontent.com/a-/AD_cFT-b=s100-p-k-no-mo" }
Questa opzione viene ignorata per le richieste non HTTP.
Ottieni un nome per la foto
Tutte le richieste al servizio Foto del luogo devono includere un nome di risorsa foto, restituito nella risposta a una richiesta di Ricerca nelle vicinanze, Ricerca testuale o Dettagli luogo. La risposta a queste richieste contiene un array photos[]
se il luogo ha contenuti fotografici correlati.
Ogni elemento di photo[]
contiene i seguenti campi:
name
: una stringa contenente il nome della risorsa della foto quando esegui una richiesta di tipo Foto. Questa stringa ha il seguente formato:places/PLACE_ID/photos/PHOTO_RESOURCE
heightPx
: l'altezza massima dell'immagine in pixel.widthPx
: la larghezza massima dell'immagine in pixel.authorAttributions[]
: eventuali attribuzioni richieste. Questo campo è sempre presente, ma potrebbe essere vuoto.
Le foto restituite dal servizio Foto provengono da vari luoghi, tra cui le foto dei proprietari di attività e quelle fornite dagli utenti. Nella maggior parte dei casi, queste foto possono essere utilizzate senza attribuzione o avranno l'attribuzione richiesta inclusa nell'immagine. Tuttavia, se l'elemento photo
restituito include un valore nel campo authorAttributions
, devi includere l'attribuzione aggiuntiva nella tua applicazione ovunque mostri l'immagine.
L'esempio seguente mostra una richiesta Dettagli luogo che include photos
nella maschera del campo, in modo che la risposta includa l'array photos[]
nella risposta:
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/ChIJ2fzCmcW7j4AR2JzfXBBoh6EDi seguito è riportato un esempio di array
photos[]
nella risposta.
... "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" } ] }, ...
Richiedi una foto per un luogo
La richiesta di esempio riportata di seguito restituisce un'immagine utilizzando la relativa risorsa name
, ridimensionandola in modo che l'altezza e la larghezza siano al massimo pari a 400 pixel:
https://places.googleapis.com/v1/places/ChIJ2fzCmcW7j4AR2JzfXBBoh6E/photos/AUacShh3_Dd8yvV2JZMtNjjbbSbFhSv-0VmUN-uasQ2Oj00XB63irPTks0-A_1rMNfdTunoOVZfVOExRRBNrupUf8TY4Kw5iQNQgf2rwcaM8hXNQg7KDyvMR5B-HzoCE1mwy2ba9yxvmtiJrdV-xBgO8c5iJL65BCd0slyI1/media?maxHeightPx=400&maxWidthPx=400&key=API_KEY
La risposta a una richiesta di Place Photo riuscita è un'immagine. Il tipo di immagine dipende da quello della foto inviata in origine.
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 tua richiesta, restituisce lo stato HTTP 400, che indica una richiesta non valida. I motivi più comuni di una richiesta non valida includono:
- Il nome della foto inviata non è stato specificato correttamente.
- La richiesta non includeva il parametro
maxHeightPx
omaxWidthPx
. - Il valore del parametro
maxHeightPx
omaxWidthtPx
è stato impostato sunull
. - Il documento
name
è scaduto. Sename
scade, invia una richiesta a Dettagli luogo (nuovo), Ricerca nelle vicinanze (nuova) o Ricerca di testo (nuova) per ottenere un nuovoname
.
Prova.
Explorer API consente di effettuare richieste di esempio in modo da acquisire familiarità con le opzioni API e API.
Per inviare una richiesta:
- Seleziona l'icona dell'API, , sul lato destro della pagina.
- Imposta il parametro
name
su:places/PLACE_ID/photos/PHOTO_RESOURCE/media
- Imposta
skipHttpRedirect
sutrue
in modo che la richiesta restituisca una risposta JSON. Per impostazione predefinita, la richiesta restituisce l'immagine, che non può essere visualizzata da Explorer API. - Seleziona il pulsante Esegui. Nel popup, scegli l'account che vuoi utilizzare per effettuare la richiesta.
Nel riquadro Explorer API, seleziona l'icona di espansione, , per espandere la finestra Explorer API.