Riquadri di Street View

Sviluppatori dello Spazio economico europeo (SEE)

Esempio di riquadri Street View

I riquadri Street View sono simili ai riquadri 2D, ma contengono immagini panoramiche acquisite 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 dà accesso a:

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

Puoi unire i riquadri delle immagini acquisite a livello stradale per creare un effetto panoramico realistico. Inoltre, puoi eseguire query su un massimo di 100 ID panorama per un insieme di località (ad esempio un percorso) e ottenere metadati più approfonditi sulla posizione della fotocamera.

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

Una volta ottenuta una chiave API, puoi accedere alle immagini di Street View seguendo questi 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 della panoramica (panoId) di una o più posizioni geografiche.

  3. Utilizza gli identificatori di panorama della 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. 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 Street View a sei livelli di zoom: da 512 pixel fino a 13.312 pixel.
https://tile.googleapis.com/v1/streetview/panoIds Consente di cercare in blocco fino a 100 località. 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'inclinazione, delle dimensioni e un 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 sulla panoramica specificata. I dettagli includono l'indirizzo correlato e i link alle panoramiche adiacenti.

Puoi trovare l'identificatore della panoramica di una o più posizioni 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 nell'esempio di codice JSON seguente.

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 attorno alla località specificata in cui cercare le panoramiche. Il valore predefinito è 50 metri.

Risposta PanoId

L'API Map Tiles tenta di trovare l'immagine panoramica più vicina a ogni località e poi 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 nell'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 GET HTTPS. Puoi recuperare informazioni sui panorami in due modi:

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

  • Tuttavia, se passi lat e lng, l'API Map Tiles restituisce i metadati per la panoramica più vicina entro il 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 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 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 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 sul fatto che gli ID panorama siano validi per più di una singola sessione utente.
lat, lng
Le coordinate (latitudine e longitudine) della panoramica. Questi valori possono essere diversi dalle coordinate passate nella richiesta perché la posizione viene agganciata alla panoramica più vicina.
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 rispetto al nord. Le direzioni vengono restituite nell'intervallo [0,360], dove 0 rappresenta il nord.
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 della panoramica.
roll
La rotazione in senso orario attorno alla linea di visione 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 di anno (AAAA) e 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 problemi con questo riquadro Street View. Devi mostrare questo link ipertestuale nell'angolo in basso a destra dell'immagine e devi includere un testo del link che dica qualcosa come "Segnala un problema con questa immagine".
addressComponent
Un Geocode strutturato che contiene i 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 la direzione è 180°, la panoramica collegata si trova a sud della panoramica corrente. Tieni presente che, a causa della natura temporanea degli ID panorama, non devi fare affidamento su questi ID per più di una singola sessione utente.

Miniature di Street View

Puoi richiedere le immagini di Street View nel formato thumbnail. Le miniature sono immagini non affiancate con dimensioni, direzione, inclinazione e campo visivo definiti dall'utente. Le immagini in miniatura hanno una risoluzione inferiore rispetto ai riquadri e dimensioni file più piccole. Per effettuare una richiesta di 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 delle 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 degli ID panorama dall'endpoint panoIds o dall'endpoint metadata, entrambi accettano le 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, da 16 a 250 pixel. Se non specifichi un'altezza, il valore predefinito è il valore massimo consentito di 250 pixel. Se specifichi un valore non compreso nell'intervallo, la miniatura si aggancia al valore valido più vicino.
width
Specifica la larghezza della miniatura in pixel, da 16 a 600 pixel. Se non specifichi una larghezza, il valore predefinito è il valore massimo consentito di 600 pixel. Se specifichi un valore non compreso nell'intervallo, la miniatura si aggancia al 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 (inclusi). Il valore predefinito è 0.
yaw
Specifica la direzione della videocamera lungo l'asse orizzontale. I valori validi sono compresi nell'intervallo 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 un'immagine di 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.

Immagini di Street View

Una volta ottenuto un panoId, puoi richiedere un riquadro di immagini di Street View. Le richieste di riquadri sono richieste GET HTTPS. 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 dei riquadri del riquadro Street View che ti interessa. I livelli di zoom nelle panoramiche in Street View devono essere compresi nell'intervallo [0,5], con 0 che 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 andata a buon fine restituisce un'immagine nel formato e nelle dimensioni specificati 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 per tileHeight. Poiché le panoramiche 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 originale, che viene divisa in riquadri.

Devi mostrare le informazioni sul copyright con ogni panoramica in Street View. La stringa da visualizzare può variare tra le panoramiche. Per ottenere le informazioni sul copyright, devi richiedere i metadati di Street View, quindi puoi fare riferimento al campo copyright della risposta. Per saperne di più, consulta Attribuzioni dei dati.