Richiesta e risposta Street View

Una richiesta di immagini di Street View è un URL HTTP nel seguente formato:

https://maps.googleapis.com/maps/api/streetview?parameters

L'immagine viene specificata utilizzando i parametri di richiesta. Come è standard negli URL, tutti i parametri sono separati utilizzando il carattere e commerciale (&). Di seguito sono elencati i parametri consentiti e i relativi valori possibili.

Parametri obbligatori

Procedi in uno dei seguenti modi:

  • location può essere una stringa di testo (ad es. Chagrin Falls, OH) o una coppia di coordinate di latitudine e longitudine (40.457375,-80.009353) e deve essere codificata come URL. Pertanto, converti indirizzi come "Municipio, New York,NY" in "Municipio+New+York,NY" prima di inviare la richiesta. L'API Street View Static si aggancia alla fotografia panoramica più vicina alla località. Quando fornisci una stringa di testo dell'indirizzo, l'API potrebbe utilizzare una posizione della videocamera diversa per mostrare meglio la posizione specificata. Quando fornisci le coordinate di latitudine e longitudine, l'API cerca una fotografia più vicina alla posizione in un raggio di 50 metri. Poiché le immagini di Street View vengono aggiornate periodicamente e le foto possono essere scattate ogni volta da posizioni leggermente diverse, è possibile che location scatti un panorama diverso quando le immagini vengono aggiornate.

Oppure:

  • pano è un ID panorama specifico. I panorami possono cambiare ID nel tempo, quindi non conservare questo ID. Salva invece l'indirizzo della località o le coordinate di latitudine e longitudine per poter aggiornare l'ID panorama. Per maggiori dettagli, vedi Aggiornare gli ID panorama eliminati.

Oltre a:

  • size specifica le dimensioni di output dell'immagine in pixel. Le dimensioni vengono specificate come {width}x{height}, ad esempio size=600x400 restituisce un'immagine di 600 pixel di larghezza e 400 di altezza.
  • key ti consente di monitorare l'utilizzo dell'API della tua applicazione nella console Google Cloud e garantisce che Google possa contattarti in merito alla tua applicazione, se necessario. Per ulteriori informazioni, vedi Ottenere una chiave e una firma.

Aggiornare gli ID panorama eliminati

Se tenti di recuperare un ID panorama e ottieni il valore ZERO_RESULTS o no, significa che l'ID panorama è stato eliminato e deve essere aggiornato.

  1. Salva l'indirizzo della località o le coordinate di latitudine e longitudine che hai utilizzato per ottenere un ID panorama in modo da poterle aggiornare in caso di necessità.

  2. Quando rilevi che l'ID di un panorama è cambiato, utilizza l'indirizzo della località originale o le coordinate di latitudine e longitudine per cercare di nuovo i panorami più vicini a quella località e ottenere un nuovo ID panorama.

Parametri facoltativi

  • signature (consigliato) è una firma digitale utilizzata per verificare che qualsiasi sito che genera richieste utilizzando la tua chiave API sia autorizzato a farlo. Le richieste che non includono una firma digitale potrebbero non andare a buon fine. Per ulteriori informazioni, vedi Ottenere una chiave e una firma.

    Nota: per i precedenti clienti del piano Premium di Google Maps Platform, la firma digitale è obbligatoria. Scopri di più sui parametri di autenticazione per i clienti con piano Premium.

  • heading indica l'orientamento della fotocamera. Sono accettati i valori compresi tra 0 e 360 (entrambi indicano il Nord, 90 indica l'Est e 180 il Sud). Se non specifichi un'intestazione, viene calcolato un valore che orienta la fotocamera verso il location specificato, dal punto in cui è stata scattata la fotografia più vicina.
  • fov (valore predefinito 90) determina il campo visivo orizzontale dell'immagine espresso in gradi, con un valore massimo consentito di 120. Quando si ha a che fare con un viewport di dimensioni fisse, come con un'immagine di Street View di dimensioni impostate, il campo visivo rappresenta in sostanza lo zoom, con numeri più piccoli che indicano un livello di zoom più elevato.


    Screenshot di un campo visivo ampio che mostra il soffitto, le pareti, il pavimento e una finestra della vasca all'interno di un acquario. Screenshot del campo visivo di un'inquadratura ravvicinata che mostra i dettagli ingranditi di una foto di Street View all'interno di un acquario.
    (Sinistra: fov=120; Destra: fov=20)

  • pitch (il valore predefinito è 0) specifica l'angolazione superiore o inferiore della fotocamera rispetto al veicolo di Street View. Spesso, ma non sempre, è orizzontale. I valori positivi fanno inclinare la fotocamera verso l'alto (90 gradi indicano che la fotocamera è rivolta verso l'alto); i valori negativi fanno inclinare la fotocamera verso il basso (-90 gradi indicano che la fotocamera è rivolta verso il basso).90-90
  • radius (il valore predefinito è 50) imposta un raggio, specificato in metri, in cui cercare un panorama, centrato sulla latitudine e sulla longitudine specificate. I valori validi sono numeri interi non negativi.
  • return_error_code indica se l'API deve restituire un codice di errore quando non viene trovata alcuna immagine (404 NOT FOUND) o in risposta a una richiesta non valida (400 BAD REQUEST). I valori validi sono true e false. Se impostato su true, viene visualizzato un messaggio di errore al posto dell'immagine grigia generica. In questo modo non sarà necessario effettuare una chiamata separata per verificare la disponibilità delle immagini.
  • source (il valore predefinito è default) limita le ricerche di Street View alle sorgenti selezionate. I valori validi sono:
    • default utilizza le origini predefinite per Street View; le ricerche non sono limitate a origini specifiche.
    • outdoor limita le ricerche alle collezioni all'aperto. Le collezioni al chiuso non sono incluse nei risultati di ricerca. Tieni presente che per la località specificata potrebbero non essere disponibili panoramiche esterne. Tieni inoltre presente che la ricerca restituisce solo i panorami in cui è possibile stabilire se sono al chiuso o all'aperto. Ad esempio, le foto sferiche non vengono restituite perché non è noto se sono state scattate all'interno o all'esterno.

Questo è un esempio di richiesta.

https://maps.googleapis.com/maps/api/streetview?size=600x300&location=46.414382,10.013988&heading=151.78&pitch=-0.76&key=YOUR_API_KEY&signature=YOUR_SIGNATURE
Uno screenshot di una foto del punto di vista a livello stradale che mostra binari ferroviari elettrificati.

Nessuna immagine disponibile

Per le località in cui non sono disponibili immagini di Street View, l'API Street View Static restituisce un'immagine generica grigia con il testo "Siamo spiacenti, non abbiamo immagini qui", come mostrato in questo esempio:

Uno screenshot dell'immagine generica visualizzata quando non sono disponibili immagini per la località specificata. Lo sfondo è marrone chiaro e viene visualizzato il testo "Siamo spiacenti, non sono disponibili immagini per questa regione".
Figura: immagine generica visualizzata quando non sono disponibili immagini per la località specificata.

Mostra solo immagini valide

Per evitare la visualizzazione dell'immagine generica e assicurarti che la tua pagina web mostri solo immagini valide dell'API Street View Static, segui questi suggerimenti:

  • Imposta il parametro return_error_code su true. In questo modo, l'API Street View Static restituisce un errore 404 NOT FOUND al posto dell'immagine grigia generica, se non è disponibile alcuna immagine per la località specificata.
  • Richiedi i metadati delle immagini di Street View per determinare se sono disponibili immagini per la località specificata prima di inviare una richiesta.