Utilizzare i token di sessione con l'API Map Tiles

Un token di sessione è un dato (un UUID) utilizzato nelle chiamate REST per identificare una sessione, una serie di scambi di messaggi correlati. Devi includere un token di sessione in tutte le richieste di riquadri 2D e di immagini di Street View. Puoi includerlo come valore di un parametro session aggiunto a tutti gli URL di richiesta.

Nell'API Map Tiles, un token sessione rappresenta un insieme definito di opzioni di visualizzazione. Ciò significa che non devi passare un insieme di opzioni di visualizzazione con ogni richiesta di riquadro. Puoi utilizzare lo stesso token di sessione per più client. Un token di sessione è attualmente valido per due settimane dalla data di emissione, ma potrebbe cambiare. Puoi sempre controllare la data e l'ora di scadenza di un token di sessione esaminando il campo expiry nel messaggio di risposta.

Nota: devi utilizzare i token di sessione per ottenere riquadri 2D e Street View, ma non per ottenere riquadri 3D.

Richiesta token sessione

Per richiedere un token di sessione, invia una richiesta POST HTTPS all'endpoint createSession, come mostrato nell'esempio seguente. Devi inviare la richiesta con un'intestazione Content-Type: application/json.

curl -X POST -d '{
  "mapType": "streetview",
  "language": "en-US",
  "region": "US"
}' \
-H 'Content-Type: application/json' \
"https://tile.googleapis.com/v1/createSession?key=YOUR_API_KEY"

Campi obbligatori

mapType

Il tipo di mappa base. Questo valore può essere uno dei seguenti:

roadmap

I riquadri di mappa standard di Google Maps.

satellite

Immagini satellitari.

terrain

Immagini del terreno. Quando selezioni terrain come tipo di mappa, devi includere anche il tipo di livello layerRoadmap (descritto nella sezione Campi facoltativi).

streetview

Panorami di Street View. Per ulteriori informazioni, consulta la sezione Riquadri Street View.

language

Un tag della lingua IETF che specifica la lingua utilizzata per visualizzare le informazioni nei riquadri. Ad esempio, en-US specifica la lingua inglese parlata negli Stati Uniti.

region

Un identificatore di regione (due lettere maiuscole) nel Repository di dati sulle impostazioni internazionali comuni che rappresenta la posizione fisica dell'utente. Ad esempio, US.

Campi facoltativi

imageFormat

Specifica il formato file da restituire. I valori validi sono jpeg o png. I file JPEG non supportano la trasparenza, pertanto non sono consigliati per i riquadri di overlay. Se non specifichi un valore imageFormat, verrà scelto automaticamente il formato migliore per il riquadro.

scale

Aumenta la dimensione degli elementi della mappa (come le etichette delle strade), mantenendo al contempo le dimensioni del riquadro e l'area di copertura del riquadro predefinito. Aumentando la scala si riduce anche il numero di etichette sulla mappa, il che riduce il disordine. I seguenti valori sono valori scale validi:

• scaleFactor1x: il valore predefinito.
• scaleFactor2x: raddoppia le dimensioni dell'etichetta e rimuove le etichette degli elementi secondari.
• scaleFactor4x: quadruplica le dimensioni delle etichette e rimuove le etichette delle caratteristiche secondarie.

I seguenti esempi mostrano l'effetto della scalabilità degli elementi della mappa.

Fattore di scala 1x	Fattore di scala 2x

highDpi

Consente di specificare se restituire riquadri ad alta risoluzione. Se il fattore di scala viene aumentato, viene utilizzato highDpi per aumentare le dimensioni del riquadro. Normalmente, aumentando il fattore di scala, il riquadro risultante viene ingrandito in un'immagine delle stesse dimensioni, determinando una qualità inferiore. Con highDpi, vengono aumentate anche le dimensioni risultanti, preservando la qualità. DPI è l'acronimo di Dots per Inch, mentre High DPI indica che il riquadro esegue il rendering utilizzando più punti per pollice del normale. Se true, il numero di pixel in ciascuna delle dimensioni x e y viene moltiplicato per il fattore di scala (ovvero 2x o 4x). L'area di copertura del riquadro rimane invariata. Questo parametro funziona solo con i valori scale di 2x o 4x. Non ha effetto sui riquadri in scala 1x.

Fattore di scala 1x	Fattore di scala 2x High DPI

layerTypes

Un array di valori che specifica i tipi di livelli aggiunti alla mappa. I valori validi sono:

layerRoadmap

Obbligatorio se specifichi terrain come tipo di mappa. Può anche essere facoltativamente sovrapposta al tipo di mappa satellite. Non ha alcun effetto sui riquadri della roadmap.

layerStreetview

Mostra strade e località compatibili con Street View utilizzando i contorni blu sulla mappa.

layerTraffic

Mostra le condizioni del traffico attuali.

styles

Un array di oggetti in stile JSON che specifica l'aspetto e il livello di dettaglio degli elementi di una mappa come strade, parchi e aree edificate. Gli stili vengono utilizzati per personalizzare la mappa base standard di Google. Il parametro styles è valido solo se il tipo di mappa è roadmap. Per la sintassi completa degli stili, consulta la documentazione di riferimento sugli stili.

overlay

Un valore booleano che specifica se layerTypes deve essere visualizzato come overlay separato o combinato con le immagini di base. Quando true, la mappa base non viene visualizzata. Se non hai definito layerTypes, questo valore viene ignorato.

Ad esempio, se richiedi un tipo di mappa satellite con un livello layerRoadmap e overlay impostato su false, verranno generati riquadri equivalenti al tipo di mappa hybrid utilizzato nell'API Maps JavaScript (immagine a sinistra). Gli stessi tipi di mappa e livelli con overlay impostato su true generano un riquadro trasparente con un overlay mappa, con uno stile adeguato per la sovrapposizione sulle immagini satellitari (immagine a destra).

overlay: falso	overlay: vero

Il seguente JSON è un esempio di un tipico corpo della richiesta che contiene i campi obbligatori e facoltativi.

{
  "mapType": "satellite",
  "language": "en-US",
  "region": "us",
  "layerTypes": [ "layerRoadmap", "layerStreetview" ],
  "overlay":  true,
  "scale": "scaleFactor1x",
  "styles": [
    {
      "stylers": [
        { "hue": "#00ffe6" },
        { "saturation": -20 }
      ]
    },{
      "featureType": "road",
      "elementType": "geometry",
      "stylers": [
        { "lightness": 100 },
        { "visibility": "simplified" }
      ]
    }
  ]
}

Questo esempio fornisce un overlay adatto alla combinazione con immagini satellitari. L'esempio contiene sia una roadmap che una sovrapposizione di Street View. La mappa risultante viene visualizzata con nomi e dati in lingua inglese, che si pronuncia negli Stati Uniti.

apiOptions: un array di valori che specifica opzioni aggiuntive da applicare. Le opzioni supportate sono:

• MCYJ5E517XR2JC - Attiva il nuovo stile di mappa. Durante il periodo di attivazione, le richieste riceveranno lo stile esistente, a meno che questo valore non venga specificato.

Risposta token sessione

Il seguente JSON è un esempio di corpo della risposta.

{
  "session": "IgAAAHGU9jnAU4KOAfwY3Bcd6eH_WxQsyocSBAdUnAr9pnvTTNXtF9c_27RBo94ytEXTDg",
  "expiry": "1361828036",
  "tileWidth": 256,
  "tileHeight": 256,
  "imageFormat": "png"
}

Il seguente elenco contiene le definizioni dei campi nel corpo della risposta.

session

Un valore del token di sessione che devi includere in tutte le richieste dell'API Map Tiles.

expiry

Una stringa che contiene l'ora (in secondi dall'epoca) in cui scade il token. Un token sessione è valido per due settimane dalla data di creazione, ma questo criterio potrebbe cambiare senza preavviso.

tileWidth

La larghezza dei riquadri misurata in pixel.

tileHeight

L'altezza dei riquadri misurata in pixel.

imageFormat

Il formato dell'immagine, che può essere png o jpeg.