Riquadri di Street View

Sviluppatori dello Spazio economico europeo (SEE)

Esempio di Street View Tiles

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

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

Puoi unire i riquadri delle immagini scattate a livello stradale per creare un effetto panoramico realistico. Puoi eseguire query su un massimo di 100 ID panorama per un insieme di posizioni (ad esempio un percorso) e ottenere metadati più approfonditi sulla posizione della videocamera.

Per unire le tessere di Street View è necessario un visualizzatore. Ad esempio, il visualizzatore Street View personalizzato per i panorami.

Una volta ottenuta una chiave API, puoi accedere alle immagini di Street View eseguendo 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 una o più località geografiche.

  3. Utilizza gli identificatori del panorama della risposta della 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. Street View Tiles.

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 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 in blocco fino a 100 sedi. Restituisce gli ID panorama 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. Consente di fornire un'intestazione, un beccheggio, le dimensioni e il 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.

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 altri, 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 il panorama più vicino a ogni località e restituisce i relativi ID panorama. 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, viene restituita una stringa vuota in quella posizione dell'array. Per un esempio, consulta il seguente codice JSON.

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

Puoi utilizzare panoIds per:

Metadati di Street View

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

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

  • Se però passi un lat e un lng, l'API Map Tiles restituisce i metadati del panorama più vicino entro il raggio di ricerca specificato.

Passare 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 trasmettere 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"

Passa l'ID panorama 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 risposta tipica 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 questa panoramica. Non devi fare affidamento sulla validità degli ID panorama per un periodo superiore a una singola sessione utente.
lat, lng
Le coordinate (latitudine e longitudine) della panoramica. Questi valori possono essere diversi dalle coordinate che hai passato nella richiesta perché la posizione si allinea al panorama più vicino.
imageHeight, imageWidth
Le dimensioni dell'immagine panoramica unita.
tileHeight, tileWidth
Le dimensioni di un singolo riquadro panoramico.
heading
La direzione della bussola, misurata in gradi, in senso orario da nord. Le intestazioni vengono restituite nell'intervallo [0,360], dove 0 rappresenta il nord esatto.
tilt
L'inclinazione della panoramica, 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 attorno alla linea di visuale 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 hanno dati relativi alla data. Tuttavia, quando è 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 collegamento ipertestuale che gli utenti possono utilizzare per segnalare problemi relativi a questa tessera di Street View. Devi visualizzare questo link ipertestuale nell'angolo in basso a destra dell'immagine e deve includere un testo del link che reciti, ad esempio, "Segnala un problema con questa immagine".
addressComponent
Un geocodice strutturato che contiene dettagli sull'indirizzo della panoramica. Per saperne di più, consulta Richieste e risposte di geocodifica nella documentazione dell'API Geocoding.
links
Un elenco di ID panorama che rimandano a questo. Contiene anche l'intestazione in cui si trova il link. Ad esempio, se l'intestazione è 180°, il panorama collegato si trova a sud rispetto al panorama corrente. Tieni presente che, a causa della natura temporanea 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 affiancate con dimensioni, intestazione, beccheggio e campo visivo definiti dall'utente. Le immagini delle miniature hanno una risoluzione inferiore rispetto alle tessere e dimensioni file più piccole. Per richiedere una miniatura, invia una richiesta GET all'endpoint thumbnail, come mostrato nel seguente prototipo di codice.

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 il seguente esempio di codice, che scarica una miniatura di immagini di Street View scattate 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

Miniatura di Street View di Whistler, Canada

Parametri obbligatori

panoId
L'ID univoco della miniatura che vuoi. Puoi ottenere i valori dell'ID panorama dall'endpoint panoIds o dall'endpoint metadata, entrambi accettano coordinate geografiche e restituiscono il valore panoId appropriato.
session
Un token di sessione valido.
key
La tua chiave API.

Parametri facoltativi

height
Specifica l'altezza della miniatura in pixel, compresa tra 16 e 250 pixel. Se non specifichi un'altezza, il valore predefinito è l'altezza massima consentita di 250 pixel. Se specifichi un valore fuori intervallo, la miniatura si sposta sul valore valido più vicino.
width
Specifica la larghezza della miniatura in pixel, compresa tra 16 e 600 pixel. Se non specifichi una larghezza, il valore predefinito è la larghezza massima consentita di 600 pixel. Se specifichi un valore fuori intervallo, la miniatura si sposta sul valore valido più vicino.
pitch
Specifica l'angolazione della videocamera lungo l'asse verticale. I valori validi sono compresi nell'intervallo da -90 a 90 (incluso). Il valore predefinito è 0.
yaw
Specifica la direzione della videocamera lungo l'asse orizzontale. I valori validi sono compresi 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 nel caso di un'immagine Street View di dimensioni prestabilite, il campo visivo rappresenta lo zoom, dove i valori più piccoli specificano un livello di zoom più elevato. Il valore predefinito è 90.

Riquadri delle immagini di Street View

Una volta ottenuto un panoId, puoi richiedere un riquadro dell'immagine di Street View. Le richieste di riquadro 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 e x e y sono le coordinate del riquadro del riquadro di Street View che ti interessa. I livelli di zoom nelle panoramiche di Street View devono essere compresi 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°

Risposte di Street View Tiles

Una richiesta di riquadro Street View riuscita restituisce un'immagine del formato e delle dimensioni che hai specificato nella risposta createSession.

Il risultato di una richiesta di riquadro riuscita

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

Livello di zoom zero

Al livello di zoom 5, viene utilizzata la panoramica a grandezza naturale, suddivisa in riquadri.

Devi mostrare le informazioni sul copyright in ogni panorama di Street View. La stringa da visualizzare può variare tra i vari panorami. Per ottenere le informazioni sul copyright, devi richiedere i metadati di Street View e poi fare riferimento al campo copyright della risposta. Per ulteriori informazioni, consulta Attribuzioni dei dati.