Metadati delle immagini di Street View

Introduzione

Le richieste di metadati dell'API Street View Static forniscono dati sui panorami di Street View. Utilizzando i metadati, puoi scoprire se un'immagine di Street View è disponibile in una determinata località, nonché ottenere l'accesso programmatico alle coordinate di latitudine e longitudine, all'ID panorama, alla data di scatto della foto e alle informazioni sul copyright dell'immagine. L'accesso a questi metadati ti consente di personalizzare il comportamento degli errori nella tua applicazione.

Nota: il valore del campo della data può variare:

• Il campo della data può avere una granularità diversa per panorami diversi. Ad esempio, il campo della data di alcuni panorami contiene un anno e un mese, mentre per altri contiene solo l'anno.
• Il campo della data viene omesso se non sono disponibili dati.

Le richieste di metadati dell'API Street View Static sono disponibili senza costi. Quando richiedi i metadati, non viene consumata alcuna quota. La quota viene consumata solo quando carichi un'immagine utilizzando l'API Street View Static.

Quando effettui richieste di metadati delle immagini di Street View, le immagini panoramiche sono precise fino a 50 metri.

Accedere ai metadati delle immagini

Una richiesta di metadati delle immagini di Street View è un URL HTTP del seguente formato:

https://maps.googleapis.com/maps/api/streetview/metadata?parameters

Nota: il protocollo https:// è obbligatorio per le richieste di metadati.

Come standard negli URL, tutti i parametri sono separati utilizzando il carattere &.

Parametri obbligatori per le richieste di metadati

Le richieste di metadati accettano gli stessi parametri URL delle richieste di immagini dell'API Street View Static, anche se sono obbligatori solo i seguenti parametri:

Procedi in uno dei seguenti modi:

• location: può essere una stringa di testo (ad esempio Chagrin Falls, OH) o una coppia di coordinate di latitudine e longitudine separate da virgola (40.457375,-80.009353).

Oppure:

• pano: un ID panorama specifico. I panorami possono cambiare ID nel tempo, quindi non conservare questo ID. Salva invece l'indirizzo della località o le coordinate di latitudine e longitudine per poter aggiornare l'ID panorama. Per maggiori dettagli, vedi Aggiornare gli ID panorama eliminati.

Oltre a:

• key e signature: la chiave API è obbligatoria per autenticare la richiesta. La firma digitale è obbligatoria anche in alcuni casi ed è sempre consigliata. Per ulteriori informazioni, consulta Ottenere una chiave e una firma.

La richiesta di metadati, con solo i parametri obbligatori, ha il seguente aspetto:

https://maps.googleapis.com/maps/api/streetview/metadata?location=&key=YOUR_API_KEY&signature=<YOUR_SIGNATURE>

o come mostrato di seguito:

https://maps.googleapis.com/maps/api/streetview/metadata?pano=&key=YOUR_API_KEY&signature=<YOUR_SIGNATURE>

Aggiornare gli ID panorama eliminati

Se tenti di recuperare un ID panorama e ottieni il valore ZERO_RESULTS o no, significa che l'ID panorama è stato eliminato e deve essere aggiornato.

1. Salva l'indirizzo della località o le coordinate di latitudine e longitudine che hai utilizzato per ottenere un ID panorama in modo da poterle aggiornare in caso di necessità.

2. Quando rilevi che l'ID di un panorama è cambiato, utilizza l'indirizzo della località originale o le coordinate di latitudine e longitudine per cercare di nuovo i panorami più vicini a quella località e ottenere un nuovo ID panorama.

Nota: poiché le immagini di Street View vengono aggiornate periodicamente e le foto possono essere scattate ogni volta da posizioni leggermente diverse, un determinato ID panorama potrebbe essere associato a un panorama diverso quando le immagini o l'ID panorama vengono aggiornati.

Parametri facoltativi per le richieste di metadati

Puoi includere i seguenti parametri nella richiesta di metadati: size, heading, fov e pitch. Tieni presente che questi parametri non influiscono sui dati relativi al panorama o sul panorama trovato. L'API consente di includere gli stessi parametri della richiesta di immagini per semplificare la creazione di una richiesta di metadati correlata a una richiesta di immagini specifica, ma per le richieste di metadati l'API ignora i parametri facoltativi e i relativi valori. Per informazioni sull'utilizzo di questi parametri, consulta la guida per gli sviluppatori dell'API Street View Static.

Formato della risposta

Le risposte dei metadati vengono restituite solo in formato JSON.

Esempi

Esempio 1: panorama trovato

I seguenti URL richiedono correttamente i metadati e l'immagine dello stesso panorama.

Richiesta e risposta dei metadati

https://maps.googleapis.com/maps/api/streetview/metadata?size=600x300&location=eiffel%20tower,%20paris,%20france&heading=-45&pitch=42&fov=110&key=YOUR_API_KEY&signature=YOUR_SIGNATURE

{
   "copyright" : "© 2017 Google",
   "date" : "2016-05",
   "location" : {
      "lat" : 48.85783227207914,
      "lng" : 2.295226175151347
   },
   "pano_id" : "tu510ie_z4ptBZYo2BGEJg",
   "status" : "OK"
}

Richiesta e risposta di immagini, dove è prevista l'immagine mancante.

https://maps.googleapis.com/maps/api/streetview?size=600x300&location=eiffel%20tower,%20paris,%20france&heading=-45&pitch=42&fov=110&key=YOUR_API_KEY&signature=YOUR_SIGNATURE

I Sample potrebbero non essere disponibili nella tua regione.

Esempio 2: panorama non trovato

I seguenti URL richiedono i metadati e l'immagine di un panorama che non è stato trovato nella posizione specificata o nelle vicinanze.

Richiesta e risposta dei metadati

https://maps.googleapis.com/maps/api/streetview/metadata?size=600x300&location=78.648401,14.194336&fov=90&heading=235&pitch=10&key=YOUR_API_KEY&signature=YOUR_SIGNATURE

{
   "status" : "ZERO_RESULTS"
}

Richiesta e risposta relative alle immagini

https://maps.googleapis.com/maps/api/streetview?size=600x300&location=78.648401,14.194336&fov=90&heading=235&pitch=10&key=YOUR_API_KEY&signature=YOUR_SIGNATURE

I Sample potrebbero non essere disponibili nella tua regione.

Codici di stato

Il campo status all'interno dell'oggetto di risposta dei metadati contiene lo stato della richiesta e potrebbe contenere informazioni di debug per aiutarti a risolvere i problemi relativi al funzionamento della richiesta di Street View. Il campo status può contenere i seguenti valori:

Stato	Descrizione
"OK"	Indica che non si sono verificati errori; viene trovato un panorama e vengono restituiti i metadati.
"ZERO_RESULTS"	Indica che non è stato possibile trovare nessun panorama vicino alla località indicata. Questa risposta può verificarsi se fornisci un ID panorama inesistente o non valido. Consulta [Aggiornare gli ID panorama eliminati](#refresh-pano).
"NOT_FOUND"	Indica che non è stato possibile trovare la stringa dell'indirizzo fornita nel parametro location. Questo messaggio può verificarsi se viene fornito un indirizzo non esistente.
"OVER_QUERY_LIMIT"	Indica che hai superato la quota giornaliera o la quota al secondo per questa API.
"REQUEST_DENIED"	Indica che la tua richiesta è stata rifiutata. Questo messaggio può verificarsi se non hai autorizzato la richiesta o se l'API Street View Static non è attivata nel progetto della console Google Cloud contenente la tua chiave API.
"INVALID_REQUEST"	In genere indica che mancano i parametri di query (indirizzo, coordinate di latitudine e longitudine o componenti).
"UNKNOWN_ERROR"	Indica che non è stato possibile elaborare la richiesta a causa di un errore del server. Questo problema è spesso temporaneo. La richiesta potrebbe andare a buon fine se riprovi.

Ulteriori informazioni

Per ulteriori informazioni sull'utilizzo dell'API Street View Static o di altri prodotti dell'API Google Maps, consulta la pagina di assistenza dell'API Maps.