Metadati delle immagini di Street View

Introduzione

Le richieste di metadati dell'API Street View Static forniscono dati sui panorami Street View. Utilizzando i metadati, puoi scoprire se un'immagine di Street View è disponibile in una determinata posizione, nonché ottenere l'accesso programmatico alle coordinate di latitudine e longitudine, all'ID panorama, alla data in cui è stata scattata la 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 data può variare:

• Il campo della data può avere una granularità diversa per i diversi panorami. Ad esempio, il campo data di alcune panoramiche contiene l'anno e il mese, mentre per altre 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 utilizzata 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 accurate fino a 50 metri.

Accedere ai metadati delle immagini

Una richiesta di metadati di un'immagine di Street View è un URL HTTP nel seguente formato:

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

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

Come di consueto negli URL, tutti i parametri sono separati dal carattere "e commerciale" (&).

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 richiesti 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 virgole (40.457375,-80.009353).

Oppure:

• pano: un ID panorama specifico. I panorama possono cambiare ID nel tempo, quindi non conservare questo ID. Salva invece l'indirizzo della posizione 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 è necessaria per autenticare la richiesta. La firma digitale è obbligatoria anche in alcuni casi e sempre consigliata. Per maggiori informazioni, vedi 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 in questo modo:

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

Aggiorna gli ID panorama eliminati

Se tenti di recuperare un ID panorama e ricevi ZERO_RESULTS o nessun valore, l'ID panorama è stato eliminato e deve essere aggiornato.

1. Salva l'indirizzo della posizione o le coordinate di latitudine e longitudine che hai utilizzato per ottenere un ID panorama, in modo da poterlo aggiornare quando necessario.

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

Nota: poiché le immagini di Street View vengono aggiornate periodicamente e le fotografie potrebbero essere scattate da posizioni leggermente diverse ogni volta, 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 l'inclusione degli 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, in cui è 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 campioni 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 campioni 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 può contenere informazioni di debug per aiutarti a risolvere il problema per cui la richiesta di Street View non funziona. 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 nessuna panoramica vicino alla posizione fornita. 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 la stringa dell'indirizzo fornita nel parametro location non è stata trovata. Questo messaggio può essere visualizzato se viene fornito un indirizzo inesistente.
"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ò essere visualizzato se non hai autorizzato la tua richiesta o se l'API Street View Static non è attivata nel progetto Google Cloud Console contenente la tua chiave API.
"INVALID_REQUEST"	Indica in genere che i parametri di query (indirizzo, coordinate di latitudine e longitudine o componenti) sono mancanti.
"UNKNOWN_ERROR"	Indica che la richiesta non è stato possibile elaborarla a causa di un errore del server. Questo problema è spesso temporaneo. Se riprovi, la richiesta potrebbe andare a buon fine.

Ulteriori informazioni

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