Riquadri di Street View

I riquadri di Street View sono simili ai riquadri 2D, ad eccezione del fatto che contengono immagini panoramiche scattate a livello stradale. Con Street View, puoi esplorare i punti di riferimento di tutto il mondo, vedere meraviglie della natura ed entrare in luoghi come musei, stadi, ristoranti o piccole attività. Questo endpoint API ti consente di accedere a:

• Riquadri Street View di Google Maps
• Metadati di Street View
• Miniature di Street View

Puoi cucire riquadri di immagini a livello stradale per creare un effetto panoramico realistico. Puoi anche eseguire query su fino a 100 ID panoramiche per un insieme di posizioni (ad esempio un percorso) e ottenere metadati più approfonditi sulla posizione della fotocamera.

Per unire i riquadri di Street View è necessario un visualizzatore. Ad esempio, il visualizzatore di una panoramica personalizzata di Street View.

Suggerimento: per ulteriori informazioni, consulta le pagine relative all'API Street View Static e al Servizio Street View.

Una volta ottenuta una chiave API, puoi accedere alle immagini di Street View svolgendo i passaggi riportati di seguito.

1. Ottenere un token di sessione. Assicurati di impostare il valore di mapType su streetview.

2. Utilizza il token di sessione per ottenere l'identificatore panoramica (panoId) di una o più località geografiche.

3. Utilizza gli identificatori panoramica della risposta della ricerca panoId per ottenere:

   1. Metadati di Street View. Puoi anche ottenere metadati di Street View passando un set di coordinate e un raggio.

   2. Miniature di Street View.

   3. Riquadri Street View.

Nota: devi mostrare le informazioni sul copyright in ogni panoramica di Street View. La stringa da visualizzare può variare tra le panoramiche. Per ottenere le informazioni sul copyright, devi richiedere i metadati di Street View, dopodiché puoi fare riferimento al campo copyright della risposta.

Metodi di Street View

Puoi accedere alle immagini e ai metadati di Street View chiamando uno dei seguenti quattro metodi.

Metodo	Descrizione
https://tile.googleapis.com/v1/streetview/tiles	Restituisce i singoli riquadri di Street View. Puoi recuperare i riquadri di Street View a sei livelli di zoom: da 512 pixel a 13.312 pixel.
https://tile.googleapis.com/v1/streetview/panoIds	Consente di cercare contemporaneamente fino a 100 località. Restituisce gli ID panoramiche per tutte le località con immagini.
https://tile.googleapis.com/v1/streetview/thumbnail	Restituisce un'immagine JPEG in miniatura di una scena di Street View. Ti consente di specificare intestazione, altezza, dimensioni e campo visivo. Le dimensioni minime sono 16 x 16 pixel. Le dimensioni massime sono 250 x 600 pixel.
https://tile.googleapis.com/v1/streetview/metadata	Fornisce informazioni dettagliate sul panorama specificato. I dettagli includono l'indirizzo correlato e i link alle panoramiche adiacenti.

Ricerca di panoIds di Street View

Puoi trovare l'identificatore panorama di una o più posizioni geografiche trasferendo le relative coordinate (lat, lng) al metodo panoIds. Il corpo della richiesta è un oggetto JSON che contiene un array locations e, facoltativamente, un radius, come mostrato nel seguente esempio di codice JSON.

curl -X POST -d '{
  "locations": [
    {"lat": -33.883837, "lng": 151.209307},
    {"lat": -33.883700, "lng": 151.210307},
    {"lat": 0, "lng": 0}
  ],
  "radius": 50
}' \
-H 'Content-Type: application/json' \
"https://tile.googleapis.com/v1/streetview/panoIds?session=YOUR_SESSION_TOKEN&key=YOUR_API_KEY"

locations

L'array locations deve contenere almeno un insieme di valori di coordinate, ma puoi includerne di più, fino a un massimo di 100.

radius

Il valore radius (misurato in metri) definisce il raggio del cerchio intorno alla posizione specificata in cui cercare le panoramiche. Il valore predefinito è 50 metri.

Risposta PanoId

L'API Map Tiles cerca di trovare la panoramica più vicina a ogni posizione, quindi restituisce i relativi ID. Una richiesta panoIds riuscita restituisce un oggetto JSON che contiene un array panoIds. L'array contiene un elenco di ID panorama, nell'ordine in cui li hai richiesti. Se l'API Map Tiles non riesce a trovare panoramiche per le località richieste, viene restituita una stringa vuota in quella posizione nell'array. Per un esempio, vedi il seguente codice JSON.

{
  "panoIds": [
    "ACfH-n2HcBvRry_3oc9grw",
    "f5DJZatBAAAXHlooS2wKbw",
    ""
  ]
}

Puoi utilizzare panoIds per:

• Richiedere metadati di Street View
• Richiedere miniature di Street View
• Richiedere riquadri Street View

Nota: gli ID panorama sono temporanei. Cioè, non durano molto. Come regola generale, non fare affidamento sul fatto che gli ID panorama siano validi per più di una singola sessione utente.

Metadati di Street View

Le richieste di metadati di Street View consentono di recuperare informazioni sulle panoramiche. Una richiesta di metadati Street View è una richiesta HTTPS GET. Puoi recuperare informazioni sulle panoramiche in due modi:

• Se trasmetti un valore pano_id, l'API Map Tiles restituisce i metadati per la panoramica in questione.

• Tuttavia, se passi un valore lat e un lng, l'API Map Tiles restituisce i metadati per la panoramica più vicina all'interno del raggio di ricerca specificato.

Passa un insieme di coordinate e un raggio

curl "https://tile.googleapis.com/v1/streetview/metadata?session=YOUR_SESSION_TOKEN&key=YOUR_API_KEY&lat=lat&lng=lng&radius=meters"

Poiché gli ID panoramica sono temporanei, ti consigliamo di trasferire un insieme di coordinate e un valore radius nella richiesta iniziale di metadati di Street View. Per un esempio, vedi il seguente snippet di codice.

curl "https://tile.googleapis.com/v1/streetview/metadata?session=YOUR_SESSION_TOKEN&key=YOUR_API_KEY&lat=47.62066&lng=-122.34923&radius=50"

Passare il panoId di un'immagine di Street View

curl "https://tile.googleapis.com/v1/streetview/metadata?session=YOUR_SESSION_TOKEN&key=YOUR_API_KEY&panoId=panoId"

Risposta dei metadati

Il seguente codice JSON è un esempio di una tipica risposta ai metadati.

{
 "panoId": "rZ9KeTyhA11i0VppYNzsSg",
 "lat": 37.420864219339165,
 "lng": -122.08446528377291,
 "imageHeight": 6656,
 "imageWidth": 13312,
 "tileHeight": 512,
 "tileWidth": 512,
 "heading": 94.35,
 "tilt": 88.39652,
 "roll": 1.7181772,
 "imageryType": "outdoor",
 "date": "2023-01",
 "copyright": "© 2023 Google",
 "reportProblemLink": "https://cbks0.googleapis.com/cbk?output=report&panoid=rZ9KeTyhA11i0VppYNzsSg&cb_client=api&cbp=1,0,,0,0&hl=en-US&gl=us",
 "addressComponents": [
  {
   "longName": "United States",
   "shortName": "United States",
   "types": [
    "country"
   ]
  },
  {
   "longName": "Mountain View, California",
   "shortName": "Mountain View, California",
   "types": [
    "locality"
   ]
  },
  {
   "longName": "Charleston Rd",
   "shortName": "Charleston Rd",
   "types": [
    "route"
   ]
  },
  {
   "longName": "1635",
   "shortName": "1635",
   "types": [
    "street_number"
   ]
  }
 ],
 "links": [
  {
   "panoId": "Yw4pqzA4FEq1qs-BwZSvSQ",
   "heading": 274.47998046875,
   "text": "Charleston Rd"
  },
  {
   "panoId": "1cODYwFRw1aZ45IignDIMw",
   "heading": 94.47999572753906,
   "text": "Charleston Rd"
  }
 ]
}

Il seguente elenco contiene le definizioni dei campi nel corpo della risposta.

panoId

L'ID univoco di questa panoramica. Non devi fare affidamento sulla validità degli ID panoramica per più di una sessione utente.

lat, lng

Le coordinate (latitudine e longitudine) del panorama. Questi valori possono essere diversi dalle coordinate che hai trasmesso nella richiesta perché la posizione aggancia alla panoramica più vicina.

imageHeight, imageWidth

Le dimensioni dell'immagine panoramica unita.

tileHeight, tileWidth

Le dimensioni di un singolo riquadro di panoramica.

heading

L'orientamento della bussola, misurata in gradi, in senso orario a partire da nord. Le intestazioni vengono restituite all'interno dell'intervallo [0,360], dove 0 rappresenta il nord dovuto.

tilt

L'inclinazione del panorama, misurata in gradi dal polo sud della panoramica all'orizzonte. I valori restituiti sono compresi nell'intervallo [0, 180]. Un valore di 90 gradi indica che l'orizzonte è già allineato all'equatore del panorama.

roll

La rotazione in senso orario intorno alla linea visiva applicata alla panoramica per livellare l'orizzonte. I valori restituiti sono compresi nell'intervallo [0, 360].

imageryType

Indica il tipo di immagine. I valori validi sono indoor e outdoor.

date

La data in cui è stata scattata l'immagine. Non tutte le immagini contengono dati sulla data. Quando invece è disponibile, il campo contiene una combinazione di anno (AAAA) e mese (MM). Ad esempio: 05-2023 o 2024.

copyright

Il testo del copyright che devi mostrare come attribuzione insieme all'immagine di Street View.

reportProblemLink

Un link ipertestuale che gli utenti possono utilizzare per segnalare problemi con questo riquadro di Street View. Devi visualizzare questo link ipertestuale nell'angolo in basso a destra dell'immagine e includere un testo del link con la dicitura "Segnala un problema con questa immagine".

addressComponent

Un codice geografico strutturato contenente dettagli sull'indirizzo del panorama. Per ulteriori informazioni, consulta la sezione Richieste e risposte di geocodifica nella documentazione dell'API Geocoding.

links

Un elenco di ID panoramica che rimandano a questo video. Contiene anche l'intestazione in cui si trova il link. Ad esempio, se l'intestazione è a 180°, la panoramica collegata deve trovarsi a sud del panorama corrente. Tieni presente che, data la natura temporanea degli ID panoramica, non dovresti utilizzarli per più di una singola sessione utente.

Miniature di Street View

Puoi richiedere immagini di Street View in formato thumbnail. Le miniature sono immagini senza riquadri con dimensioni, intestazione, altezza e campo visivo definiti dall'utente. Le immagini in miniatura hanno una risoluzione inferiore rispetto ai riquadri e le dimensioni dei file sono inferiori. Puoi effettuare una richiesta di miniature inviando una richiesta GET all'endpoint thumbnail, come dimostrato nel seguente prototipo di codice.

Nota: in questo esempio, i valori dei campi racchiusi tra parentesi quadre sono indicati gli intervalli. Ad esempio, height può variare da 16 a 250 pixel.

curl "https://tile.googleapis.com/v1/streetview/thumbnail?session=YOUR_SESSION_TOKEN&key=YOUR_API_KEY&panoId=panoId&height=FROM_16_TO_250&width=FROM_16_TO_600&pitch=FROM-90_TO_90&yaw=FROM-360_TO_360&fov=FROM_30_TO_120"

Prendiamo in considerazione l'esempio di codice riportato di seguito, che scarica una miniatura di immagini Street View scattate a Whistler, Canada.

curl "https://tile.googleapis.com/v1/streetview/thumbnail?session=YOUR_SESSION_TOKEN&key=YOUR_API_KEY&panoId=Zzl28rqGJgaL2IdkUleP8A&height=200&width=200&pitch=0&yaw=250&fov=80" --output /tmp/example_thumbnail.png

Parametri obbligatori

panoId

L'ID univoco della miniatura che vuoi usare. Puoi ottenere i valori ID panoramica dall'endpoint panoIds o dall'endpoint metadata, che accettano entrambe le coordinate geografiche e restituiscono il valore panoId appropriato.

session

Un token di sessione valido.

key

La chiave API.

Parametri facoltativi

height

Specifica l'altezza della miniatura in pixel, che va da 16 pixel a 250 pixel. Se non specifichi un'altezza, per impostazione predefinita l'altezza corrisponde al valore massimo consentito di 250 pixel. Se specifichi un valore non compreso nell'intervallo, la miniatura viene agganciata al valore valido più vicino.

width

Specifica la larghezza della miniatura in pixel, che va da 16 pixel a 600 pixel. Se non specifichi una larghezza, per impostazione predefinita viene utilizzato il valore massimo consentito di 600 pixel. Se specifichi un valore non compreso nell'intervallo, la miniatura viene agganciata al valore valido più vicino.

pitch

Specifica l'angolazione della fotocamera lungo l'asse verticale. I valori validi sono compresi nell'intervallo compreso tra -90 e 90 (inclusi). Il valore predefinito è 0.

yaw

Specifica la direzione della fotocamera lungo l'asse orizzontale. I valori validi sono compresi nell'intervallo compreso tra -360 e 360 (inclusi). Il valore predefinito è 0.

fov

Specifica il campo visivo orizzontale, espresso in gradi, con un valore massimo di 120. In un'area visibile con dimensioni fisse, come nel caso di un'immagine Street View di una dimensione impostata, il campo visivo rappresenta lo zoom, laddove i valori più piccoli indicano un livello di zoom più elevato. Il valore predefinito è 90.

Riquadri di immagini di Street View

Una volta creato un panoId, puoi richiedere un riquadro immagine di Street View. Le richieste di riquadro sono richieste HTTPS GET. Considera l'esempio che segue.

curl "https://tile.googleapis.com/v1/streetview/tiles/z/x/y?session=YOUR_SESSION_TOKEN&key=YOUR_API_KEY&panoId=panoId"

In questo esempio di codice, z è il livello di zoom, mentre x e y sono le coordinate dei riquadri del riquadro Street View che ti interessa. I livelli di zoom nelle panoramiche Street View devono essere compresi nell'intervallo [0,5] e 0 rappresenta il campo visivo più ampio.

Livello di zoom	Campo visivo approssimativo
0	360°
1	180°
2	90°
3	45°
4	22,5°
5	11,25°

Nota: le immagini di Street View provengono da due fonti: Google (immagini non pubbliche controllate dallo sviluppatore) e contenuti pubblici (generati dagli utenti o contenuti pubblici). Tieni presente che non è possibile utilizzare una sola fonte di immagini di Street View rispetto a un'altra. Scopri di più sulle nostre Norme sulla privacy delle immagini di Street View.

Risposte ai riquadri di Street View

Una richiesta di riquadro Street View andata a buon fine restituisce un'immagine con il formato e le dimensioni specificati nella risposta createSession.

A livello di zoom zero, l'intera panoramica viene ridimensionata in un riquadro di dimensioni tileWidth di tileHeight. Poiché le panoramiche sono più grandi nella dimensione x, il riquadro conterrà uno spazio vuoto nella dimensione y:

A livello di zoom cinque, viene utilizzata la panoramica a grandezza originale e viene suddivisa in riquadri.

Suggerimento: per calcolare i valori massimi di x e y, dividi imageHeight e imageWidth per tileHeight e tileWidth.

Informazioni sul copyright

Devi mostrare le informazioni sul copyright su ogni panoramica di Street View. La stringa da visualizzare può variare tra le panoramiche. Per ottenere le informazioni sul copyright, devi richiedere i metadati di Street View, dopodiché puoi fare riferimento al campo copyright della risposta. Per ulteriori informazioni, consulta Attribuzioni dei dati.