Foto del luogo (novità)

Seleziona la piattaforma: Android iOS Servizio web
Sviluppatori dello Spazio economico europeo (SEE)

Introduzione

Il servizio Place Photos (New) è un'API di sola lettura che ti consente di aggiungere contenuti fotografici di alta qualità alla tua applicazione. Place Photos (New) ti dà accesso a milioni di foto archiviate nel database di Places.

Quando recuperi le informazioni sui luoghi utilizzando una richiesta Place Details (New), Nearby Search (New) o Ricerca testuale (New), puoi anche richiedere risorse fotografiche per i contenuti fotografici pertinenti. Utilizzando Place Photos (New), puoi quindi accedere alle foto a cui viene fatto riferimento e ridimensionare l' immagine alla dimensione ottimale per la tua applicazione.

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

Richieste Place Photos (New)

Una richiesta Place Photos (New) è una richiesta HTTP GET a un URL nel formato: 
https://places.googleapis.com/v1/NAME/media?key=API_KEY&PARAMETERS

Dove i seguenti parametri sono obbligatori:

  • NAME contiene il nome della risorsa della foto.
  • API_KEY contiene la chiave API.
  • PARAMETERS contiene il parametro maxHeightPx, il parametro maxWidthPx o entrambi.

L'elenco completo dei parametri obbligatori e facoltativi è descritto di seguito.

Parametri obbligatori

Nome foto

Una stringa identificatore che identifica in modo univoco una foto. I nomi delle foto vengono restituiti da una richiesta Place Details (New), Nearby Search (New) o Ricerca testuale (New) nella proprietà name di ogni elemento dell'array photos[].

Per un esempio, vedi Recuperare il nome di una foto.

maxHeightPx e maxWidthPx

Specifica l'altezza e la larghezza massime previste dell'immagine, in pixel. Se l'immagine è più piccola dei valori specificati, verrà restituita l'immagine originale. Se l'immagine è più grande in una delle due dimensioni, verrà scalata in modo da corrispondere alla dimensione più piccola delle due, limitata alle 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), effettua 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.

Recuperare il nome di una foto

Tutte le richieste a Place Photos (New) devono includere il nome della risorsa foto , restituito nella risposta a una richiesta Nearby Search (New), Text Search (New) o Place Details (New). 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 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 da Place Photos (New) provengono da una serie di località, tra cui proprietari di attività e foto inviate dagli 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 visualizzi l'immagine.

L'esempio seguente mostra una richiesta Place Details (New) che include photos nella maschera dei campi 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 il relativo name della risorsa, ridimensionandola in modo che abbia un'altezza e una larghezza massime di 400 pixel:

https://places.googleapis.com/v1/places/ChIJ2fzCmcW7j4AR2JzfXBBoh6E/photos/ATKogpeivkIjQ1FT7QmbeT33nBSwqLhdPvIWHfrG1WfmgrFjeZYpS_Ls7c7rj8jejN9QGzlx4GoAH0atSvUzATDrgrZic_tTEJdeITdWL-oG3TWi5HqZoLozrjTaxoAIxmROHfV5KXVcLeTdCC6kmZExSy0CLVIG3lAPIgmvUiewNf-ZHYE4-jXYwPQpWHJgqVosvZJ6KWEgowEA-qRAzNTu9VH6BPFqHakGQ7EqBAeYOiU8Dh-xIQC8FcBJiTi0xB4tr-MYXUaF0p_AqzAhJcDE6FAgLqG1s7EsME0o36w2nDRHA-IuoISBC3SIahINE3Xwq2FzEZE6TpNTFVfgTpdPhV8CGLeqrauHn2I6ePm-2hA8-87aO7aClXKJJVzlQ1dc_JuHz6Ks07d2gglw-ZQ3ibCTF5lMtCF9O-9JHyRQXsfuXw/media?maxHeightPx=400&maxWidthPx=400&key=API_KEY

La risposta a una richiesta Place Photos (New) riuscita è un'immagine.

Codici di errore

Le richieste Place Photos (New) possono restituire i seguenti codici di errore.

Quota superata (403)

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:

Notifica di superamento della quota

Richiesta non valida (404)

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 per una richiesta non valida sono:

  • Il nome della foto inviato non è stato specificato correttamente specificato.
  • La richiesta non includeva il maxHeightPx o il maxWidthPx parametro.
  • Il valore del maxHeightPx o il parametro maxWidthtPx è stato impostato su null.
  • Il name è scaduto. Se name scade, effettua una richiesta a Place Details (New), Nearby Search (New) o Ricerca testuale (New) per ottenere un nuovo name.

Troppe richieste (429)

Google consiglia di caricare le foto on demand. Se tenti di mostrare tutte le immagini di un luogo contemporaneamente, il server potrebbe restituire uno stato HTTP 429 che indica il caricamento di troppe foto contemporaneamente. Se ricevi questo messaggio di errore, contatta l'assistenza e richiedi un aumento della quota.

Fai una prova!

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

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. Nella finestra di dialogo, scegli l'account che vuoi utilizzare per effettuare la richiesta.

  5. Nel riquadro Explorer API, seleziona l'icona a schermo intero per espandere la finestra Explorer API.