Richiesta e risposta di Street View

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

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

L'immagine viene specificata utilizzando i parametri di richiesta. Come per gli URL, tutti i parametri sono separati utilizzando la e commerciale (&). Di seguito sono elencati i parametri consentiti e i rispettivi valori possibili.

Parametri obbligatori

Procedi in uno dei seguenti modi:

  • location può essere una stringa di testo (ad esempio Chagrin Falls, OH) o un valore lat/lng (40.457375,-80.009353) e deve essere codificata in URL, pertanto indirizzi come "City Hall, New York, NY" devono essere convertiti in "City+Hall,New+York,NY", prima della firma della richiesta. L'API Street View Static verrà agganciata alla panoramica fotografata più vicina a questa località. Quando viene fornita una stringa di testo per l'indirizzo, l'API può utilizzare una posizione della fotocamera diversa per mostrare meglio la posizione specificata. Quando viene fornito un latitudine/longitudine, l'API cerca un raggio di 50 metri per una foto più vicina a questa località. Poiché le immagini di Street View vengono aggiornate periodicamente e le fotografie possono essere scattate ogni volta in posizioni leggermente diverse, è possibile che l'immagine location venga visualizzata in una panoramica diversa quando le immagini vengono aggiornate.

Oppure:

  • pano è un ID panoramica specifico. In genere sono stabili.

Inoltre:

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

Parametri facoltativi

  • signature (consigliata) è 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 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'intestazione della bussola della videocamera. I valori accettati vanno da 0 a 360 (entrambi i valori che indicano il nord, con 90 che indica l'est e 180 a sud). Se non viene specificata alcuna intestazione, verrà calcolato un valore che indirizza la fotocamera verso l'elemento location specificato, dal momento in cui è stata scattata la fotografia più vicina.
  • fov (il valore predefinito è 90) determina il campo visivo orizzontale dell'immagine. Il campo visivo è espresso in gradi, con un valore massimo consentito di 120. Quando hai a che fare con un'area visibile a dimensioni fisse, come con un'immagine di Street View di una dimensione impostata, il campo visivo in sostanza rappresenta lo zoom, con numeri più piccoli che indicano un livello di zoom più elevato.


    Screenshot di un campo visivo ad ampio raggio che mostra il soffitto, le pareti, il pavimento e una finestra del serbatoio 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 superiore o inferiore della fotocamera rispetto al veicolo Street View. Spesso, ma non sempre, è orizzontale. Valori positivi indicano l'angolazione della videocamera verso l'alto (con 90 gradi che indicano l'angolazione verticale); i valori negativi indicano che la fotocamera è rivolta verso il basso (con -90 che indica la direzione verso il basso).
  • radius (il valore predefinito è 50) imposta un raggio, specificato in metri, in cui cercare un panorama, centrato sulla latitudine e 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 di Street View alle origini selezionate. I valori validi sono:
    • default utilizza le sorgenti predefinite per Street View; le ricerche non sono limitate a sorgenti specifiche.
    • outdoor limita le ricerche alle raccolte all'aperto. Le raccolte per interni non sono incluse nei risultati di ricerca. Tieni presente che potrebbero non esistere panoramiche esterne per il luogo specificato. Inoltre, ricorda che la ricerca restituisce solo le panoramiche in cui è possibile determinare se sono al chiuso o all'aperto. Ad esempio, le foto sferiche non vengono restituite perché non è noto se si trovano in ambienti interni o esterni.

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 panoramica a livello stradale che mostra un binario ferroviario elettrizzante.

Nessuna immagine disponibile

Per i luoghi 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", 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 "Siamo 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 mostrare l'immagine generica, e per assicurarti che sulla tua pagina web vengano mostrate solo immagini valide dell'API Street View, 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.
  • Prima di inviare una richiesta, richiedi i metadati delle immagini di Street View per determinare se sono disponibili immagini per la località specificata.