Utilizzare i token di sessione con l'API Map Tiles

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

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 su più client. Attualmente, un token di sessione è valido per due settimane dal momento dell'emissione, ma questo dato potrebbe cambiare. Puoi sempre controllare la scadenza di un token di sessione osservando il campo expiry nel messaggio di risposta.

Richiesta di token di 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 della mappa di Google Maps dipinti standard.

satellite

Immagini satellitari

.

terrain

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

streetview

Panoramiche in Street View. Per ulteriori informazioni, consulta Riquadri di Street View.

language

Un tag 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 identificativo della regione del Common Locale Data Repository (due lettere maiuscole) che rappresenta la posizione fisica dell'utente. Ad esempio, US.

Campi facoltativi

imageFormat

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

scale

Consente di aumentare le dimensioni degli elementi della mappa (come le etichette delle strade), mantenendo le dimensioni dei riquadri e l'area di copertura del riquadro predefinito. L'aumento della scala consente inoltre di ridurre il numero di etichette sulla mappa, riducendo così le interferenze. I seguenti valori sono valori scale validi:

• scaleFactor1x: il valore predefinito.
• scaleFactor2x: raddoppia le dimensioni delle etichette e rimuove le etichette delle funzionalità secondarie.
• scaleFactor4x: quadruplica le dimensioni delle etichette e rimuove le etichette delle funzionalità secondarie.

Gli esempi riportati di seguito mostrano l'effetto della scalatura degli elementi della mappa.

Fattore di scala 1x	Fattore di scala 2x

highDpi

Specifica se restituire riquadri ad alta risoluzione. Se il fattore di scala viene aumentato, highDpi viene utilizzato per aumentare le dimensioni del riquadro. In genere, l'aumento del fattore di scala ingrandisce il riquadro risultante in un'immagine delle stesse dimensioni, il che riduce la qualità. Con highDpi, anche le dimensioni risultanti vengono incrementate, preservando la qualità. DPI sta per Dots per Inch e DPI elevato indica che il riquadro viene visualizzato utilizzando più punti per pollice rispetto al normale. Se true, il numero di pixel in ciascuna delle dimensioni x e y viene moltiplicato per il coefficiente di scala (ovvero 2x o 4x). L'area di copertura del riquadro rimane invariata. Questo parametro funziona solo con valori scale pari a 2x o 4x. Non ha alcun effetto sulle schede con scala 1x.

Fattore di scala 1x	Fattore di scala 2x DPI elevato

layerTypes

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

layerRoadmap

Obbligatorio se specifichi terrain come tipo di mappa. Se vuoi, puoi anche sovrapporre il tipo di mappa satellite. Non ha alcun effetto sui riquadri della roadmap.

layerStreetview

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

layerTraffic

Mostra le condizioni di traffico attuali.

styles

Un array di oggetti JSON di stile che specificano l'aspetto e il livello di dettaglio degli elementi della mappa, come strade, parchi e aree urbanizzate. La personalizzazione viene utilizzata 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 il riferimento agli 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, la richiesta di un tipo di mappa satellite con un livello layerRoadmap e overlay impostato su false genera riquadri equivalenti al tipo di mappa hybrid utilizzato nell'API Maps JavaScript (immagine a sinistra). Gli stessi tipi di mappa e livello con overlay impostato su true generano un riquadro trasparente con un overlay mappa, stilizzato in modo appropriato per la sovrapposizione alle immagini satellitari (immagine a destra).

overlay: false	overlay: true

Il seguente JSON è un esempio di un tipico corpo della richiesta contenente sia campi obbligatori che 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 le immagini satellite. L'esempio contiene sia una mappa stradale che un overlay di Street View. La mappa risultante viene visualizzata con nomi e dati in lingua inglese, come viene parlato negli Stati Uniti.

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

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

Risposta del token di sessione

Il seguente JSON è un esempio di corpo di 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 da includere in tutte le richieste dell'API Map Tiles.

expiry

Una stringa contenente la data e l'ora (in secondi dall'epoca) di scadenza del token. Un token sessione è valido per due settimane dal momento della sua creazione, ma queste norme potrebbero cambiare senza preavviso.

tileWidth

La larghezza delle riquadri misurata in pixel.

tileHeight

L'altezza delle riquadri misurata in pixel.

imageFormat

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