Utilizzare i token di sessione con l'API Map Tiles

Sviluppatori dello Spazio economico europeo (SEE)

Un token di sessione è un dato (un UUID) 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 immagini 2D Tiles e Street View. Lo includi come valore di un parametro session aggiunto a tutti gli URL di richiesta.

Nell'API Map Tiles, un token di 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. Un token di sessione è attualmente valido per due settimane dalla data di emissione, ma questo potrebbe cambiare. Puoi sempre controllare la scadenza di un token di sessione esaminando 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 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
Panoramiche in Street View. Per saperne di più, consulta Riquadri Street View.
language

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

region

Un identificatore di regione Common Locale Data Repository (due lettere maiuscole) 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 imageFormat, viene scelto automaticamente il formato migliore per il riquadro.
scale

Aumenta le dimensioni degli elementi della mappa (come le etichette delle strade), mantenendo le dimensioni e l'area di copertura del riquadro predefinito. L'aumento della scala riduce anche il numero di etichette sulla mappa, riducendo così il disordine. I seguenti valori sono valori scale validi:

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

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

Fattore di scalabilità 1x Fattore di scalabilità 2x
Mappa che mostra il fattore di scalabilità 1x Mappa che mostra il fattore di scalabilità 2x
highDpi
Specifica se restituire tile ad alta risoluzione. Se il fattore di scalabilità viene aumentato, viene utilizzato highDpi per aumentare le dimensioni del riquadro. In genere, l'aumento del fattore di scalabilità ingrandisce il riquadro risultante in un'immagine della stessa dimensione, il che riduce la qualità. Con highDpi, anche le dimensioni risultanti aumentano, preservando la qualità. DPI sta per "punti per pollice" e DPI elevato significa che il rendering del riquadro utilizza 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 scalabilità (ovvero 2x o 4x). L'area di copertura del riquadro rimane invariata. Questo parametro funziona solo con valori scale di 2x o 4x. Non ha alcun effetto sulle tessere con scala 1x.
Fattore di scalabilità 1x Fattore di scalabilità 2x DPI elevato
Mappa visualizzata con risoluzione normale Mappa visualizzata con risoluzione DPI elevata 2x
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 sovrapposto facoltativamente al tipo di mappa satellite. Non ha alcun effetto sui riquadri della mappa stradale.
layerStreetview
Mostra le strade e le località abilitate per Street View utilizzando contorni blu sulla mappa.
layerTraffic
Mostra le condizioni del traffico attuali.
styles

Un array di oggetti di stile JSON che specificano l'aspetto e il livello di dettaglio degli elementi della mappa, come strade, parchi e aree edificate. Lo stile viene utilizzato per personalizzare la mappa base standard di Google. Il parametro styles è valido solo se il tipo di mappa è roadmap. Per la sintassi completa dello stile, consulta il riferimento per lo stile.

overlay

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

Ad esempio, se richiedi un tipo di mappa satellite con un livello layerRoadmap e overlay impostato su false, vengono restituite sezioni 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 della mappa, con uno stile appropriato per la sovrapposizione alle immagini satellitari (immagine a destra).

overlay: false overlay: true
Overlay impostato su false Overlay impostato su true

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

Risposta del token di 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 tue richieste API Map Tiles.
expiry
Una stringa che contiene l'ora (in secondi dall'epoca) in cui il token scade. Un token di sessione è valido per due settimane dalla data di creazione, ma questa policy 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.