Richiesta e risposta Street View

Sviluppatori dello Spazio economico europeo (SEE)

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 della richiesta. Come di consueto negli URL, tutti i parametri sono 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 come URL. Quindi, converti indirizzi come "City Hall, New York, NY" in "City+Hall,New+York,NY" prima di inviare la richiesta. L'API Street View Static esegue lo snap alla fotografia panoramica più vicina alla posizione. Quando fornisci una stringa di testo dell'indirizzo, l'API potrebbe utilizzare una posizione della videocamera diversa per visualizzare 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 fotografie potrebbero essere scattate da posizioni leggermente diverse ogni volta, è possibile che il tuo location si sposti su un panorama diverso quando le immagini vengono aggiornate.

Oppure:

  • pano è un ID panorama specifico. Gli ID dei panorama possono cambiare nel tempo, quindi non conservarli. Salva invece l'indirizzo della posizione 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 sono 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 maggiori informazioni, consulta Ottenere una chiave e una firma.

Aggiorna gli ID panorama eliminati

Se tenti di recuperare un ID panorama e ricevi ZERO_RESULTS o nessun valore, l'ID panorama è 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 panorama, in modo da poterlo aggiornare quando necessario.

  2. Quando rilevi che un ID panorama è cambiato, utilizza l'indirizzo della posizione originale o le coordinate di latitudine e longitudine per cercare di nuovo i panorama più vicini a quella posizione 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 maggiori informazioni, consulta Ottenere una chiave e una firma.

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

  • heading indica l'orientamento della videocamera. 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 orientamento, viene calcolato un valore che orienta la fotocamera verso il location specificato, dal punto in cui è stata scattata la fotografia più ravvicinata.
  • fov (il 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 nel caso di un'immagine di Street View di dimensioni impostate, il campo visivo rappresenta essenzialmente lo zoom, con numeri più piccoli che indicano un livello di zoom più elevato.


    Screenshot di un ampio campo visivo che mostra il soffitto, le pareti, il pavimento e la finestra di una vasca all'interno di un acquario. Screenshot di un campo visivo di primo piano, che mostra il 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 di Street View. Spesso, ma non sempre, è orizzontale. Valori positivi indicano che l'angolazione della fotocamera è verso l'alto (90° indica che la fotocamera è posizionata in verticale e rivolta verso l'alto); valori negativi indicano che l'angolazione della fotocamera è verso il basso (-90° indica che la fotocamera è posizionata in verticale e rivolta verso il basso).
  • radius (il valore predefinito è 50) imposta un raggio, specificato in metri, in cui cercare un panorama, centrato sulla latitudine e sulla longitudine indicate. 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 origini specifiche.
    • outdoor limita le ricerche alle raccolte all'aperto. Le raccolte indoor non sono incluse nei risultati di ricerca. Tieni presente che le panoramiche esterne potrebbero non esistere per la posizione specificata. Tieni presente inoltre che la ricerca restituisce solo i panorami in cui è possibile determinare se si trovano all'interno o all'esterno. Ad esempio, le foto sferiche non vengono restituite perché non è noto se siano state scattate all'interno o all'esterno.

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 del punto di vista a livello stradale che mostra i binari 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 abbiamo immagini qui", come mostrato in questo esempio:

Uno screenshot dell'immagine generica visualizzata quando non sono disponibili immagini per la posizione specificata. Lo sfondo è marrone chiaro e mostra il testo "Siamo spiacenti, non sono disponibili immagini per questa regione".
Figura: immagine generica visualizzata quando non sono disponibili immagini per la posizione 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 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 posizione specificata prima di inviare una richiesta.