Richiesta e risposta Street View

Sviluppatori dello Spazio economico europeo (SEE)

Una richiesta di immagine 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 di consueto negli URL, tutti i parametri sono separati dal 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 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, prima di inviare la richiesta, converti indirizzi come "City Hall, New York, NY" in "City+Hall,New+York,NY". 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 località specificata. Quando fornisci le coordinate di latitudine e longitudine, l'API cerca una fotografia più vicina alla località in un raggio di 50 metri. Poiché le immagini di Street View vengono aggiornate periodicamente e le fotografie possono essere scattate ogni volta da posizioni leggermente diverse, è possibile che la tua location venga agganciata a un panorama diverso quando le immagini vengono aggiornate.

Oppure:

  • pano è un ID panorama specifico. L'ID delle panoramiche può cambiare nel tempo, quindi non mantenerlo. Salva invece l'indirizzo della località o le coordinate di latitudine e longitudine per poter aggiornare l'ID panorama. Per maggiori dettagli, consulta Aggiorna gli ID panorama eliminati.

Inoltre:

  • 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 delle API della tua applicazione nella console Google Cloud e garantisce che Google possa contattarti in merito alla tua applicazione, se necessario. Per saperne di più, consulta Ottieni una chiave e una firma.

Aggiorna gli ID panorama eliminati

Se provi a recuperare un ID panorama e ottieni ZERO_RESULTS o nessun valore, 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 poterlo 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 i panorami più vicini a quella posizione e ottenere un nuovo ID panorama.

Parametri facoltativi

  • signature (consigliata) è 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 saperne di più, consulta Ottieni una chiave e una firma.

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

  • heading indica la direzione della bussola della videocamera. I valori accettati sono compresi tra 0 e 360 (entrambi i valori indicano il nord, 90 indica l'est e 180 il sud). Se non specifichi un'intestazione, viene calcolato un valore che indirizza la videocamera verso il 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. Quando si ha a che fare con un'area visibile di dimensioni fisse, come un'immagine di Street View di dimensioni fisse, il campo visivo rappresenta essenzialmente 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 la finestra di una vasca all'interno di un acquario. Screenshot di un campo visivo di un primo piano, che mostra i dettagli ingranditi di una foto di Street View all'interno di un acquario.
    (A sinistra: fov=120; a destra: fov=20)

  • pitch (il valore predefinito è 0) specifica l'angolo verso l'alto o verso il basso della fotocamera rispetto al veicolo Street View. Spesso, ma non sempre, si tratta di una linea orizzontale piatta. I valori positivi inclinano la videocamera verso l'alto (90 gradi indica la posizione verticale verso l'alto); i valori negativi inclinano la videocamera verso il basso (-90 indica la posizione verticale 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 - Non trovato) 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à dell'immagine.
  • 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 collezioni per interni non sono incluse nei risultati di ricerca. Tieni presente che potrebbero non esistere panoramiche esterne per la località specificata. Tieni presente inoltre che la ricerca restituisce solo le panoramiche per le quali è possibile determinare se sono interne o esterne. Ad esempio, le fotosfere non vengono restituite perché non è noto se siano interne o esterne.

Ecco 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 di un punto di vista a livello stradale che mostra 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 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 mostra 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 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 anziché l'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.