Richiesta e risposta Street View

Una richiesta di immagine di Street View è un URL HTTP in questo formato:

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

L'immagine viene specificata utilizzando i parametri della richiesta. Come standard negli URL, tutti i parametri sono separati dalla 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 esempio Chagrin Falls, OH) o una coppia di coordinate di latitudine e longitudine (40.457375,-80.009353) e deve essere con codifica URL. Di conseguenza, prima di inviare la richiesta, converti gli indirizzi, ad esempio "Municipio, New York, NY" in "Municipio,New+York,NY". L'API Street View Static esegue l'agganciamento alla fotografia panoramica più vicina alla località. Quando fornisci una stringa di testo dell'indirizzo, l'API potrebbe utilizzare una posizione della fotocamera diversa per visualizzare meglio la posizione specificata. Quando fornisci le coordinate di latitudine e longitudine, l'API cerca in un raggio di 50 metri la fotografia più vicina al luogo. Poiché le immagini di Street View vengono aggiornate periodicamente e le fotografie possono essere scattate da posizioni leggermente diverse ogni volta, è possibile che il tuo location possa agganciarsi a una panoramica diversa 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 in modo da poter aggiornare l'ID panoramica. Per maggiori dettagli, consulta la sezione Aggiornare gli ID panoramiche eliminati.

Inoltre:

  • size specifica la dimensione di output dell'immagine in pixel. La dimensione è specificata come {width}x{height}; ad esempio, size=600x400 restituisce un'immagine larga 600 pixel e alta 400.
  • key ti consente di monitorare l'utilizzo delle API della tua applicazione in Google Cloud Console e garantisce che Google possa contattarti in merito alla tua applicazione, se necessario. Per saperne di più, vedi Ottenere una chiave e una firma.

Aggiorna gli ID panoramica eliminati

Se tenti di recuperare un ID panoramica e ottenere il valore ZERO_RESULTS o nessun valore, l'ID panoramica è stato eliminato e deve essere aggiornato.

  1. Salva l'indirizzo della posizione o le coordinate di latitudine e longitudine utilizzate per ottenere l'ID panoramica, in modo da poter aggiornare quando necessario.

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

Parametri facoltativi

  • signature (consigliato) è una firma digitale utilizzata per verificare che qualsiasi sito che genera richieste utilizzando la chiave API sia autorizzato a farlo. Le richieste che non includono una firma digitale potrebbero non riuscire. Per saperne di più, vedi Ottenere una chiave e una firma.

    Nota: per i clienti che non hanno sottoscritto un piano Premium di Google Maps Platform, la firma digitale è obbligatoria. Scopri di più sui parametri di autenticazione per i clienti del piano Premium.

  • heading indica la direzione della fotocamera. I valori accettati sono compresi tra 0 e 360 (entrambi indicano il Nord, 90 indica l'Est e 180 Sud). Se non specifichi un'intestazione, viene calcolato un valore che indirizza la fotocamera verso l'elemento location specificato, dal punto in cui è stata scattata la foto più vicina.
  • fov (il valore predefinito è 90) determina il campo visivo orizzontale dell'immagine espresso in gradi, con un valore massimo consentito di 120. Nell'ambito di un'area visibile con dimensioni fisse, come nel caso di un'immagine di Street View di una dimensione impostata, il campo visivo essenzialmente rappresenta lo zoom, mentre numeri più piccoli 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 di un campo visivo in primo piano, che mostra un dettaglio ingrandito 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 verso l'alto o verso il basso della fotocamera rispetto al veicolo Street View. Spesso, ma non sempre, è orizzontale piatta. Valori positivi indicano che l'angolazione della fotocamera è verso l'alto (con 90 gradi che indica che la fotocamera è posizionata in verticale); valori negativi indicano che l'angolazione della fotocamera è verso il basso (con -90 che indica che la fotocamera è dritta verso il basso).
  • radius (il valore predefinito è 50) imposta un raggio, specificato in metri, in cui cercare una panoramica, 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 impostata su true, viene restituito 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 in Street View alle origini selezionate. I valori validi sono:
    • default utilizza le sorgenti predefinite per Street View; le ricerche non sono limitate a fonti specifiche.
    • outdoor limita le ricerche alle raccolte di immagini all'aperto. Le raccolte di interni non sono incluse nei risultati di ricerca. Tieni presente che i panorami all'aperto potrebbero non esistere per la località specificata. Tieni inoltre presente che la ricerca restituisce solo le panoramiche in cui è possibile determinare se questi ultimi si trovano al chiuso o all'aperto. Ad esempio, le foto PhotoSpheres non vengono restituite perché non è noto se siano al chiuso o all'aperto.

Questa è una richiesta di esempio.

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
Screenshot di una foto a livello stradale che mostra i binari ferroviari elettrificati.

Nessuna immagine disponibile

Per le località in cui le immagini di Street View non sono disponibili, l'API Street View Static restituisce un'immagine generica grigia con il testo "Spiacenti, non sono disponibili 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 mostra il testo "Spiacenti, non sono presenti immagini qui".
Figura: immagine generica visualizzata quando non sono disponibili immagini per la località specificata.

Mostra solo immagini valide

Per evitare di visualizzare l'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 NON TROVATO al posto dell'immagine grigia generica, se non è disponibile nessuna immagine per la località specificata.
  • Richiedi i metadati delle immagini di Street View per stabilire se sono disponibili immagini per la località specificata prima di inviare la richiesta.