Foto del luogo (novità)

Seleziona 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. Foto del luogo (nuovo) ti consente di accedere a milioni di foto archiviate nel database di Places.

Quando ottieni informazioni sui luoghi utilizzando una richiesta Dettagli luogo (nuovo), Ricerca nelle vicinanze (nuova) o Ricerca di testo (nuova), puoi anche richiedere risorse fotografiche per contenuti fotografici pertinenti. Utilizzando Place Photos (New), puoi accedere alle foto a cui viene fatto riferimento e ridimensionare l'immagine alla dimensione ottimale per la tua applicazione.

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

Richieste di Place Photos (nuovo)

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 sono richiesti 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

Una stringa identificatore 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 di testo (nuova) 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 che corrisponda alla più piccola delle due dimensioni, mantenendo le proporzioni originali. 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 (impostazione predefinita), esegui un reindirizzamento HTTP all'immagine per restituirla. Se true, ignora 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 a Place Photos (New) devono includere il nome di una 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 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 posizioni, tra cui foto di proprietari di attività e foto inviate dagli utenti. Nella maggior parte dei casi, queste foto possono essere utilizzate senza attribuzione o 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 visualizzi l'immagine.

Il seguente esempio mostra una richiesta Place Details (New) che include photos nella maschera del 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 del luogo

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

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 di Place Photos (New) possono restituire i seguenti codici di errore.

Quota superata (403)

Se la tua richiesta supera la quota disponibile, il server restituisce uno stato HTTP 403 e mostra 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 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.
  • L'incentivo name è scaduto. Se name scade, invia una richiesta a Place Details (New), Nearby Search (New) o Text Search (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.

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