Foto del luogo (nuova)

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 parametro maxWidthPx 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/ChIJ2fzCmcW7j4AR2JzfXBBoh6E
Di 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:

Immagine di superamento quota

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 o maxWidthPx.
  • Il valore del parametro maxHeightPx o maxWidthtPx è stato impostato su null.
  • Il documento name è scaduto. Se name scade, invia una richiesta a Dettagli luogo (nuovo), Ricerca nelle vicinanze (nuova) o Ricerca di testo (nuova) per ottenere un nuovo name.

Prova.

Explorer API consente di effettuare richieste di esempio in modo da acquisire familiarità con le opzioni API e API.

Per inviare una richiesta:

  1. Seleziona l'icona dell'API, Espandi Explorer API., sul lato destro della pagina.
  2. Imposta il parametro name su: 
    places/PLACE_ID/photos/PHOTO_RESOURCE/media
  3. Imposta skipHttpRedirect su true 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.
  4. Seleziona il pulsante Esegui. Nel popup, scegli l'account che vuoi utilizzare per effettuare la richiesta.

  5. Nel riquadro Explorer API, seleziona l'icona di espansione, Espandi Explorer API., per espandere la finestra Explorer API.