Metadati delle immagini di Street View

Introduzione

Le richieste di metadati dell'API Street View Static forniscono dati sulle panoramiche 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 della panoramica, 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 della data può variare:

• Il campo della data può avere una granularità diversa per panoramiche diverse. Ad esempio, il campo della data per alcune panoramiche contiene un anno e un 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 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 accurate entro 50 metri.

Accedi ai metadati delle immagini

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

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

Nota: il protocollo https:// è obbligatorio 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 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 virgole (40.457375,-80.009353).

Oppure:

• pano: un ID panorama specifico. Gli ID delle panoramiche possono cambiare nel tempo, quindi non memorizzarli. Salva invece l'indirizzo della località o le coordinate di latitudine e longitudine per poter aggiornare l'ID panorama. Per maggiori dettagli, consulta Aggiorna gli ID panorama eliminati.

Inoltre:

• key e signature: la chiave API è obbligatoria per autenticare la richiesta. La firma digitale è richiesta anche in alcuni casi ed è sempre consigliata. Per saperne di più, consulta Ottieni 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 questo:

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

Aggiorna gli ID panorama eliminati

Se provi a recuperare un ID panorama e ottieni ZERO_RESULTS o nessun valore, 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 poterlo aggiornare quando necessario.

2. Quando rilevi che l'ID di un 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 possono essere scattate ogni volta da posizioni leggermente diverse, un determinato ID panorama potrebbe agganciarsi a un panorama diverso quando le immagini o l'ID panorama vengono aggiornati.

Parametri facoltativi per le richieste di metadati

Nella richiesta di metadati puoi includere i seguenti parametri: size, heading, fov e pitch. Tieni presente che questi parametri non influiscono sui dati relativi alla panoramica o sulla panoramica trovata. 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 di Street View Static API.

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 della stessa panoramica.

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

Esempio 2: panorama non trovato

I seguenti URL richiedono i metadati e l'immagine di una panoramica che non è stato possibile trovare nella località 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 per le 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

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 i problemi 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 trovata una panoramica e vengono restituiti i metadati.
"ZERO_RESULTS"	Indica che non è stato possibile trovare alcuna panoramica vicino alla località fornita. Questa risposta può verificarsi se fornisci un ID panorama non esistente o non valido. Consulta [Aggiorna gli ID panorama eliminati](#refresh-pano).
"NOT_FOUND"	Indica che non è stato possibile trovare la stringa dell'indirizzo fornita nel parametro location. Questo messaggio potrebbe 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 potrebbe essere visualizzato 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 i parametri di query (indirizzo, coordinate di latitudine e longitudine o componenti) sono mancanti.
"UNKNOWN_ERROR"	Indica che non è stato possibile elaborare la richiesta a causa di un errore del server. Spesso si tratta di un problema temporaneo. La richiesta potrebbe andare a buon fine se riprovi.

Ulteriori informazioni

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