Richiesta e risposta Street View

Una richiesta di immagine 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 avviene per gli URL, tutti i parametri vengono separati dal carattere "e commerciale" (&). I parametri consentiti e i relativi valori possibili sono elencati di seguito.

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 codificata in formato URL. Pertanto, converti indirizzi quali "Municipio, Roma, RM" in "Museo+Roma, Milano", prima di inviare la richiesta. L'API Street View Static scatta alla fotografia panoramica più vicina al luogo. 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 alla località. Poiché le immagini di Street View vengono aggiornate periodicamente e le fotografie possono essere scattate ogni volta da posizioni leggermente diverse, è possibile che location si sposti su una panoramica diversa quando le immagini vengono aggiornate.

Oppure:

  • pano è un ID panoramica specifico. I panorami potrebbero cambiare ID nel tempo, quindi non conservare questo ID. Salva invece l'indirizzo della posizione o le coordinate di latitudine e longitudine per aggiornare l'ID del panorama. Per maggiori dettagli, consulta Aggiornare gli ID delle panoramiche eliminati.

Inoltre:

  • size specifica le dimensioni 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 consente di monitorare l'utilizzo dell'API da parte dell'applicazione nella console Google Cloud e garantisce che Google possa contattarti in merito alla tua applicazione se necessario. Per ulteriori informazioni, consulta l'articolo Ottenere una chiave e una firma.

Aggiorna gli ID panoramiche eliminati

Se provi a recuperare l'ID di una panoramica e visualizzi ZERO_RESULTS o nessun valore, significa che l'ID panoramica è stato eliminato e deve essere aggiornato.

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

  2. Quando rilevi che l'ID di una panoramica è 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 (consigliata) è una firma digitale utilizzata per verificare che qualsiasi sito che genera richieste utilizzando la chiave API sia autorizzato. Le richieste che non includono una firma digitale potrebbero non riuscire. Per ulteriori informazioni, consulta l'articolo Ottenere una chiave e una firma.

    Nota: per gli ex clienti del 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 l'orientamento della fotocamera. I valori accettati sono compresi tra 0 e 360 (entrambi i valori indicano il nord, con 90 che indica l'est e 180 sud). Se non specifichi un'intestazione, viene calcolato un valore che indirizza la fotocamera verso l'oggetto location specificato, dal punto in cui è stata scattata la fotografia più vicina.
  • fov (il valore predefinito è 90) determina il campo visivo orizzontale dell'immagine espresso in gradi, con un valore massimo consentito di 120. Nel caso di un'area visibile di dimensioni fisse, come nel caso di un'immagine di Street View di dimensioni prestabilite, 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 la finestra della vasca all'interno di un acquario. Screenshot di un campo visivo ravvicinato che mostra i dettagli con lo zoom aumentato di una foto di Street View all'interno di un acquario.
    (Sinistra: fov=120; Destra: fov=20)

  • pitch (il valore predefinito è 0) consente di specificare l'angolazione superiore o inferiore della fotocamera rispetto al veicolo di Street View. Spesso, ma non sempre, è orizzontale. Valori positivi indicano che l'angolazione della fotocamera è verso l'alto (90 gradi indica che la fotocamera è posizionata in posizione dritta verso l'alto); valori negativi indicano che l'angolazione della fotocamera è verso il basso (con -90 che indica che indica che la fotocamera è in posizione dritta verso il basso).
  • radius (il valore predefinito è 50) imposta un raggio, specificato in metri, entro il quale 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 restituito un messaggio di errore al posto dell'immagine grigia generica. In questo modo non è necessario effettuare una chiamata separata per verificare la disponibilità delle immagini.
  • source (il valore predefinito è default) limita le ricerche di Street View alle origini selezionate. I valori validi sono:
    • default utilizza le origini predefinite per Street View; le ricerche non sono limitate a fonti specifiche.
    • outdoor limita le ricerche alle raccolte di contenuti all'aperto. Le raccolte di immagini di interni non sono incluse nei risultati di ricerca. Tieni presente che le panoramiche di esterni potrebbero non esistere per la posizione specificata. Inoltre, tieni presente che la ricerca restituisce solo le panoramiche dove è possibile determinare se si trovano all'interno o all'esterno. Ad esempio, le PhotoSphere non vengono restituite perché non è noto se si trovano in ambienti interni o esterni.

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
Uno screenshot di una foto di un punto di osservazione a livello stradale che mostra i binari elettrificati della ferrovia.

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 "Siamo 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 abbiamo 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 nella pagina web vengano visualizzate 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.