Riquadri di Street View

I riquadri di Street View sono simili ai riquadri 2D tranne per il fatto che contengono immagini panoramiche scattate a livello stradale. Con Street View puoi esplorare punti di riferimento internazionali, scoprire meraviglie della natura ed entrare direttamente in musei, stadi, ristoranti o piccole attività. Questo endpoint dell'API ti consente di accedere a:

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

Puoi unire i riquadri di immagini scattati a livello stradale per creare un effetto panoramico reale. Inoltre, puoi eseguire query su fino a 100 ID panorama per un insieme di località (ad esempio un itinerario) e ottenere metadati più dettagliati sulla posizione della fotocamera.

È necessario un visualizzatore per unire i riquadri di Street View. Ad esempio, il visualizzatore di panorami personalizzati di Street View.

Suggerimento: per ulteriori informazioni, consulta l'API Street View Static e il servizio Street View.

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

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

2. Utilizza il token di sessione per ottenere l'identificatore del panorama (panoId) di uno o più luoghi geografici.

3. Utilizza gli identificatori dei panorami dalla risposta di ricerca panoId per ottenere:

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

   2. Miniature di Street View.

   3. Riquadri Street View.

Nota: devi mostrare le informazioni sul copyright in ogni panorama di Street View. La stringa da visualizzare può variare da un panorama all'altro. Per ottenere le informazioni sul copyright, devi richiedere i metadati di Street View, quindi 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 fino a 13.312 pixel.
https://tile.googleapis.com/v1/streetview/panoIds	Ti consente di cercare collettivamente fino a 100 località. Restituisce gli ID dei panorami 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 fornire rotta, inclinazione, 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 ai panorami adiacenti.

Ricerca di panoId di Street View

Puoi trovare l'identificatore del panorama di una o più località geografiche passando 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 i panorami. Il valore predefinito è 50 metri.

Risposta PanoId

L'API Map Tiles tenta di trovare la panoramica più vicina a ogni località e poi restituisce i relativi ID. Una richiesta panoIds riuscita restituisce un oggetto JSON contenente 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, in quella posizione dell'array viene restituita una stringa vuota. Per un esempio, consulta il seguente codice JSON.

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

Puoi utilizzare panoIds per:

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

Nota: gli ID panorama sono temporanei. In altre parole, non durano a lungo. Come regola generale, non fare affidamento sulla validità degli ID panorama per più di una singola sessione utente.

Metadati di Street View

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

• Se passi un pano_id, l'API Map Tiles restituisce i metadati del panorama.

• Tuttavia, se passi lat e lng, l'API Map Tiles restituisce i metadati per il panorama più vicino 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 panorama sono temporanei, ti consigliamo di passare un insieme di coordinate e un valore radius nella richiesta iniziale dei metadati di Street View. Per un esempio, consulta lo snippet di codice seguente.

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 dei 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 questo panorama. Non devi fare affidamento sul fatto che gli ID panorama siano validi per più di una singola sessione utente.

lat, lng

Le coordinate (latitudine e longitudine) del panorama. Questi valori possono essere diversi dalle coordinate che hai passato nella richiesta perché la posizione si aggancia al panorama più vicino.

imageHeight, imageWidth

Le dimensioni dell'immagine panoramica cucita.

tileHeight, tileWidth

Le dimensioni di un singolo riquadro panoramico.

heading

La direzione della bussola, misurata in gradi, in senso orario da nord. Le tracce vengono riportate nell'intervallo [0,360], dove 0 rappresenta il nord.

tilt

L'inclinazione del panorama, misurata in gradi dal polo sud del panorama all'orizzonte. I valori restituiti rientrano 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 attorno alla linea di vista applicata al panorama per allineare l'orizzonte. I valori restituiti rientrano 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 hanno dati sulla data. Tuttavia, se è disponibile, questo campo contiene una combinazione dell'anno (AAAA) e del mese (MM). Ad esempio: 2023-05 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 i problemi relativi a questa scheda di Street View. Devi visualizzare questo link ipertestuale nell'angolo in basso a destra dell'immagine e deve includere un testo del link che dica qualcosa di simile a "Segnala un problema con questa immagine".

addressComponent

Un codice geografico strutturato che contiene i dettagli dell'indirizzo del panorama. Per saperne di più, consulta la sezione Richieste e risposte di geocodifica nella documentazione dell'API Geocoding.

links

Un elenco di ID panorama collegati a questo. Contiene anche la voce in cui si trova il link. Ad esempio, se l'orientamento è di 180°, il panorama collegato si trova a sud del panorama corrente. Tieni presente che, a causa della natura transitoria degli ID panorama, non devi fare affidamento su questi per più di una sessione utente.

Miniature di Street View

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

Nota: i valori di campo racchiusi tra parentesi quadre in questo esempio mostrano 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"

Considera l'esempio di codice che segue, che scarica una miniatura delle immagini di Street View acquisite a Whistler, in 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 ti interessa. Puoi ottenere i valori ID panorama dall'endpoint panoIds o dall'endpoint metadata, entrambi accettano coordinate geografiche e restituiscono il panoId appropriato.

session

Un token di sessione valido.

key

La tua chiave API.

Parametri facoltativi

height

Specifica l'altezza della miniatura in pixel, da 16 a 250 pixel. Se non specifichi un'altezza, il valore predefinito è il valore massimo consentito di 250 pixel. Se specifichi un valore fuori intervallo, la miniatura si aggancia al valore valido più vicino.

width

Specifica la larghezza della miniatura in pixel, da 16 a 600. Se non specifichi una larghezza, il valore predefinito è il valore massimo consentito di 600 pixel. Se specifichi un valore fuori intervallo, la miniatura si aggancia al valore valido più vicino.

pitch

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

yaw

Specifica la direzione della fotocamera lungo l'asse orizzontale. I valori validi rientrano 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. Quando si ha a che fare con un'area visibile di dimensioni fisse, come con un'immagine di Street View di dimensioni prestabilite, il campo visivo rappresenta lo zoom; i valori più piccoli specificano un livello di zoom più elevato. Il valore predefinito è 90.

Riquadri di immagini di Street View

Una volta ottenuto un panoId, puoi richiedere un riquadro di immagini di Street View. Le richieste di riquadri sono richieste HTTPS GET. Considera l'esempio seguente.

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 del riquadro del riquadro di Street View che ti interessa. I livelli di zoom nei panorami di Street View devono rientrare nell'intervallo [0,5], dove 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 dagli sviluppatori) e dal pubblico (contenuti generati dagli utenti pubblici). Tieni presente che non è possibile utilizzare solo una fonte di immagini di Street View rispetto all'altra. Scopri di più sulle nostre norme sulla privacy relative alle immagini di Street View.

Risposte ai riquadri di Street View

Una richiesta di riquadri di Street View andata a buon fine restituisce un'immagine del formato e delle dimensioni specificati nella risposta createSession.

Al livello di zoom zero, l'intero panorama viene ridimensionato in un riquadro di dimensioni tileWidth x tileHeight. Poiché i panorami sono più grandi nella dimensione x, la scheda conterrà uno spazio vuoto nella dimensione y:

Al livello di zoom 5, viene utilizzato il panorama a grandezza naturale e diviso in riquadri.

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

Informazioni sul copyright

Devi mostrare le informazioni sul copyright in ogni panorama di Street View. La stringa da visualizzare può variare da un panorama all'altro. Per ottenere le informazioni sul copyright, devi richiedere i metadati di Street View, quindi puoi fare riferimento al campo copyright della risposta. Per ulteriori informazioni, consulta Attribuzione dei dati.