Riquadri di Street View

Esempio di Street ViewI 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 in tutto il mondo, 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 cucire insieme riquadri di immagini scattate a livello della strada per creare un effetto panoramico realistico. 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.

Una volta ottenuta una chiave API, puoi accedere alle immagini di Street View seguendo questa procedura.

  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 panorama (panoId) di una o più località geografiche.

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

    1. Metadati 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.

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 Consente di effettuare ricerche collettive 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 specificare intestazione, presentazione, 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. che includono l'indirizzo correlato e i link a panoramiche 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 contenente 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. Ad esempio, vedi il codice JSON seguente.

{
  "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 GET HTTPS. Puoi recuperare le informazioni sui panorami in due modi:

  • Se superi un pano_id, l'API Map Tiles restituisce i metadati per tale 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.

Trasmettere un insieme di coordinate e di 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
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 della panoramica 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 i tuoi utenti possono utilizzare per segnalare problemi con questo riquadro 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 singola sessione utente.

Miniature di Street View

Puoi richiedere le immagini di Street View in formato thumbnail. Le miniature sono immagini non in riquadro con dimensioni, intestazione, inclinazione e campo visivo definiti dall'utente. Le miniature hanno una risoluzione inferiore ai riquadri e dimensioni file più piccole. Puoi effettuare una richiesta di miniatura inviando 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 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

Miniatura di Street View di Whistler, in Canada

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, con un intervallo compreso tra 16 e 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, che va da 16 a 600 pixel. Se non specifichi una larghezza, il valore predefinito è 600 pixel, il valore massimo consentito. 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°

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.

Il risultato di una richiesta di riquadro andata a buon fine

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

Livello di zoom zero

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

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.