Utilizzare i token di sessione con l'API Map Tiles
Mantieni tutto organizzato con le raccolte
Salva e classifica i contenuti in base alle tue preferenze.
Sviluppatori dello Spazio economico europeo (SEE)
Un token di sessione è un insieme di dati (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 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 di sessione rappresenta un insieme definito di
opzioni di visualizzazione. Ciò significa che non devi trasmettere un insieme di opzioni di visualizzazione con
ogni richiesta di riquadro. Puoi utilizzare lo stesso token di sessione in più client.
Un token di sessione è attualmente valido per due settimane dalla data di emissione, ma questo potrebbe cambiare. Puoi sempre controllare la data di 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.
Il tipo di mappa base. Questo valore può essere uno dei seguenti:
roadmap
I riquadri della mappa dipinta standard di Google Maps.
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 di Street View. Per ulteriori informazioni, vedi
Tessere 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 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
le tessere di overlay. Se non specifichi un imageFormat, il formato migliore per
il riquadro viene scelto automaticamente.
scale
Aumenta le dimensioni degli elementi della mappa (ad esempio le etichette delle strade), mantenendo
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 validi per scale:
scaleFactor1x: il valore predefinito.
scaleFactor2x: raddoppia le dimensioni delle etichette e rimuove le etichette delle funzionalità secondarie.
scaleFactor4x: quadruplica le dimensioni dell'etichetta e rimuove le etichette delle funzionalità secondarie.
Gli esempi seguenti mostrano l'effetto del ridimensionamento 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. Normalmente,
aumentando il fattore di scala, il riquadro risultante viene ingrandito in un'immagine delle
stesse dimensioni, 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 riquadro viene visualizzato 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 valori scale di 2x o 4x. Non ha alcun effetto sui riquadri 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. Può anche essere sovrapposto
facoltativamente al tipo di mappa satellite. Non ha alcun effetto sui riquadri della roadmap.
layerStreetview
Mostra le strade e le località abilitate a 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
delle funzionalità della mappa, come strade, parchi e aree edificate. 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 dello stile, consulta il
Riferimento allo stile.
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 alcun 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 una sovrapposizione della mappa, formattata in modo appropriato per la sovrapposizione alle immagini satellitari
(immagine a destra).
overlay: false
overlay: true
Il seguente JSON è un esempio di corpo della richiesta tipico che contiene campi obbligatori e facoltativi.
Questo esempio fornisce un overlay adatto alla combinazione con immagini
satellitari. L'esempio contiene sia una mappa stradale sia una sovrapposizione di Street View. La mappa
risultante viene visualizzata con nomi e dati in inglese, come
parlato negli Stati Uniti.
Risposta del token di sessione
Il seguente JSON è un esempio di corpo della risposta.
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 dell'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 queste norme potrebbero 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.
[null,null,["Ultimo aggiornamento 2025-09-04 UTC."],[[["\u003cp\u003eSession tokens, represented as UUIDs, are required for accessing 2D Tiles and Street View imagery through the Map Tiles API but not for 3D Tiles.\u003c/p\u003e\n"],["\u003cp\u003eThey define display options for a session, eliminating the need to send them with each tile request and can be used across multiple clients.\u003c/p\u003e\n"],["\u003cp\u003eTo obtain a session token, an HTTPS POST request is sent to the \u003ccode\u003ecreateSession\u003c/code\u003e endpoint with parameters defining the map type, language, region, and optional display settings.\u003c/p\u003e\n"],["\u003cp\u003eThe response includes the session token, its expiration time, and tile dimensions, with the token remaining valid for approximately two weeks.\u003c/p\u003e\n"]]],[],null,["# Use session tokens with Map Tiles API\n\n**European Economic Area (EEA) developers** If your billing address is in the European Economic Area, effective on 8 July 2025, the [Google\n| Maps Platform EEA Terms of Service](https://cloud.google.com/terms/maps-platform/eea) will apply to your use of the Services. [Learn more](/maps/comms/eea/faq). In addition, certain content from the Map Tiles API will no longer be returned. [Learn more](/maps/comms/eea/map-tiles).\n\nA session token is a piece of data (a\n[UUID](https://en.wikipedia.org/wiki/Universally_unique_identifier))\nthat is used in REST calls to identify a\n[session](https://en.wikipedia.org/wiki/Session_(computer_science))---a\nseries of related message exchanges. You must include a session token in all\nrequests for 2D Tiles and Street View imagery.\nYou include it as the value of a `session` parameter appended to all request\nURLs.\n\nIn the Map Tiles API, a session token represents a defined set of\ndisplay options. It means you don't have to pass a set of display options with\neach tile request. You can use the same session token across multiple clients.\nA session token is currently valid for two weeks from its\nissue time, but this might change. You can always check the expiration time of a\nsession token by looking at the `expiry` field in the response message.\n| **Note:** You need to use session tokens for getting 2D Tiles and Street View Tiles, but not for getting 3D Tiles.\n\nSession token request\n---------------------\n\nTo request a session token, send an HTTPS POST request to the `createSession`\nendpoint, as shown in the following example. You must send the request with a\n`Content-Type: application/json` header. \n\n```json\ncurl -X POST -d '{\n \"mapType\": \"streetview\",\n \"language\": \"en-US\",\n \"region\": \"US\"\n}' \\\n-H 'Content-Type: application/json' \\\n\"https://tile.googleapis.com/v1/createSession?key=YOUR_API_KEY\"\n```\n\n### Required fields\n\n`mapType`\n\n: The type of base map. This value can be one of the following:\n\n `roadmap`\n : The standard Google Maps painted map tiles.\n\n `satellite`\n : Satellite imagery.\n\n `terrain`\n : Terrain imagery. When selecting `terrain` as the map type, you must also\n include the `layerRoadmap` layer type (described in the\n [Optional fields](/maps/documentation/tile/session_tokens#optional_fields)\n section).\n\n `streetview`\n : Street View panoramas. For more information, see\n [Street View Tiles](/maps/documentation/tile/streetview).\n\n`language`\n\n: An\n [IETF language tag](https://en.wikipedia.org/wiki/IETF_language_tag)\n that specifies the language used to display information on the tiles. For\n example, `en-US` specifies the English language as spoken in the United States.\n\n`region`\n\n: A\n [Common Locale Data Repository](https://cldr.unicode.org/)\n region identifier (two uppercase letters) that represents the physical location\n of the user. For example, `US`.\n\n### Optional fields\n\n`imageFormat`\n: Specifies the file format to return. Valid values are either `jpeg` or `png`.\n JPEG files don't support transparency, therefore they aren't recommended for\n overlay tiles. If you don't specify an `imageFormat`, then the best format for\n the tile is chosen automatically.\n\n`scale`\n\n: Scales-up the size of map elements (such as road labels), while retaining the\n tile size and coverage area of the default tile. Increasing the scale also\n reduces the number of labels on the map, which reduces clutter. The following\n values are valid `scale` values:\n\n - `scaleFactor1x`: The default.\n - `scaleFactor2x`: Doubles label size and removes minor feature labels.\n - `scaleFactor4x`: Quadruples label size and removes minor feature labels.\n\nThe following examples demonstrate the effect of scaling map elements.\n\n| Scale Factor 1x | Scale Factor 2x |\n|-----------------|-----------------|\n| | |\n\n`highDpi`\n: Specifies whether to return high-resolution tiles. If the scale-factor is\n increased, `highDpi` is used to increase the size of the tile. Normally,\n increasing the scale factor enlarges the resulting tile into an image of the\n same size, which lowers quality. With `highDpi`, the resulting size is also\n increased, preserving quality. DPI stands for Dots per Inch, and High DPI means\n the tile renders using more dots per inch than normal. If `true`, then the\n number of pixels in each of the x and y dimensions is multiplied by the scale\n factor (that is , 2x or 4x). The coverage area of the tile remains unchanged.\n This parameter works only with `scale` values of 2x or 4x. It has no effect on\n 1x scale tiles.\n\n| Scale Factor 1x | Scale Factor 2x High DPI |\n|-----------------|--------------------------|\n| | |\n\n`layerTypes`\n\n: An array of values that specifies the layer types added to the map. Valid\n values are:\n\n `layerRoadmap`\n : Required if you specify `terrain` as the map type. Can also be optionally\n overlaid on the `satellite` map type. Has no effect on roadmap tiles.\n\n `layerStreetview`\n : Shows Street View-enabled streets and locations using blue outlines on the\n map.\n\n `layerTraffic`\n : Displays current traffic conditions.\n\n`styles`\n\n: An array of JSON style objects that specify the appearance and detail level of\n map features such as roads, parks, and built-up areas. Styling is used to\n customize the standard Google base map. The `styles` parameter is valid only if\n the map type is `roadmap`. For the complete style syntax, see the\n [Style Reference](/maps/documentation/tile/style-reference).\n\n`overlay`\n\n: A boolean value that specifies whether `layerTypes` should be\n rendered as a separate overlay, or combined with the base imagery. When\n `true`, the base map isn't displayed. If you haven't defined any `layerTypes`,\n then this value is ignored.\n\nFor example, requesting a `satellite` map type with a `layerRoadmap` layer, and\n`overlay` set to `false` results in tiles equivalent to the `hybrid` map type\nused in the Maps JavaScript API (left image). The same\nmap and layer types with `overlay` set to `true` results in a transparent tile\nwith a map overlay, styled appropriately for overlaying over satellite imagery\n(right image).\n\n| `overlay`: false | `overlay`: true |\n|------------------|-----------------|\n| | |\n\nThe following JSON is an example of a typical request body that contains both\nrequired and optional fields. \n\n {\n \"mapType\": \"satellite\",\n \"language\": \"en-US\",\n \"region\": \"us\",\n \"layerTypes\": [ \"layerRoadmap\", \"layerStreetview\" ],\n \"overlay\": true,\n \"scale\": \"scaleFactor1x\",\n \"styles\": [\n {\n \"stylers\": [\n { \"hue\": \"#00ffe6\" },\n { \"saturation\": -20 }\n ]\n },{\n \"featureType\": \"road\",\n \"elementType\": \"geometry\",\n \"stylers\": [\n { \"lightness\": 100 },\n { \"visibility\": \"simplified\" }\n ]\n }\n ]\n }\n\nThis example provides an overlay that's suitable for combining with satellite\nimagery. The example contains both a roadmap and street view overlay. The\nresulting map is rendered with names and data in the English language, as it's\nspoken in the United States.\n\nSession token response\n----------------------\n\nThe following JSON is an example response body. \n\n {\n \"session\": \"IgAAAHGU9jnAU4KOAfwY3Bcd6eH_WxQsyocSBAdUnAr9pnvTTNXtF9c_27RBo94ytEXTDg\",\n \"expiry\": \"1361828036\",\n \"tileWidth\": 256,\n \"tileHeight\": 256,\n \"imageFormat\": \"png\"\n }\n\nThe following list contains definitions of the fields in the response body.\n\n`session`\n: A session token value that you must include in all of your Map Tiles API\n requests.\n\n`expiry`\n: A string that contains the time (in seconds since the epoch) at which the token\n expires. A session token is valid for two weeks from its creation\n time, but this policy might change without notice.\n\n`tileWidth`\n: The width of the tiles measured in pixels.\n\n`tileHeight`\n: The height of the tiles measured in pixels.\n\n`imageFormat`\n: The image format, which can be either `png` or `jpeg`."]]
