Foto del luogo (nuova)

Il servizio Foto di luoghi (nuovo) è 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 archiviate nel database di Places.

Quando ottieni informazioni sui luoghi utilizzando una richiesta di dettagli sui luoghi, una ricerca nelle vicinanze o una ricerca di testo, puoi anche richiedere risorse fotografiche per contenuti fotografici pertinenti. Utilizzando il servizio Foto, puoi accedere alle foto a cui fai riferimento e ridimensionare l'immagine in base alle dimensioni ottimali per la tua applicazione.

L'API Explorer ti consente di effettuare richieste in tempo reale per familiarizzare con l'API e le opzioni dell'API:

Prova!

Richieste di foto del luogo

Una richiesta di foto di un luogo è una richiesta HTTP GET a un URL nel seguente formato:

https://places.googleapis.com/v1/NAME/media?key=API_KEY&PARAMETERS

Dove sono obbligatori i seguenti parametri:

• NAME contiene il nome della 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 della foto

Un identificatore di stringa che identifica in modo univoco una foto. I nomi delle foto vengono restituiti da una richiesta Dettagli dei luoghi (novità), Ricerca nelle vicinanze (novità) o Ricerca di testo (novità) nella proprietà name di ogni elemento dell'array photos[].

Per un esempio, consulta Assegnare un nome a una foto.

maxHeightPx e maxWidthPx

Specifica l'altezza e la larghezza massime desiderate, in pixel, dell'immagine. Se l'immagine è più piccola rispetto ai valori specificati, verrà restituita l'immagine originale. Se l'immagine è più grande in una delle due dimensioni, verrà ridimensionata in base alla dimensione più piccola, rispettando le proporzioni originali. Entrambe le proprietà maxheight e maxwidth accettano un numero intero compreso tra 1 e 4800.

Devi specificare maxHeightPx, maxWidthPx o entrambi.

Parametri facoltativi

skipHttpRedirect

Se false (valore predefinito), esegui un reindirizzamento HTTP all'immagine per restituirla. Se true, salta il reindirizzamento e restituisci una risposta JSON contenente i dettagli 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.

Ottenere il nome di una foto

Tutte le richieste al servizio Foto dei luoghi devono includere un nome della risorsa foto restituito nella risposta a una ricerca nelle vicinanze, una ricerca di testo o una richiesta di dettagli del 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 effettui una richiesta di foto. Questa stringa è nel 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 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 authorAttributions, devi includere l'attribuzione aggiuntiva nella tua applicazione ovunque venga visualizzata l'immagine.

L'esempio seguente mostra una richiesta di dettagli sul luogo che include photos nella maschera di campo in modo che la risposta includa l'array photos[]:

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"
          }
        ]
      },    ...

Richiedere una foto di un luogo

La richiesta di esempio riportata di seguito restituisce un'immagine utilizzando la risorsa name, ridimensionandola in modo che abbia al massimo 400 pixel di altezza e larghezza:

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 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:

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 cui una richiesta non è valida:

• 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.
• name è scaduto. Se name scade, invia una richiesta a Dettagli dei luoghi (novità), Ricerca nelle vicinanze (novità) o Ricerca di testo (novità) per ottenere un nuovo name.

Prova

L'Explorer API ti consente di effettuare richieste di esempio per familiarizzare con l'API e le relative opzioni.

Per effettuare una richiesta:

1. Seleziona l'icona dell'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 dall'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, , per espandere la finestra di Explorer API.