Używanie tokenów sesji z interfejsem Map Tiles API
Zadbaj o dobrą organizację dzięki kolekcji
Zapisuj i kategoryzuj treści zgodnie ze swoimi preferencjami.
Deweloperzy z Europejskiego Obszaru Gospodarczego (EOG)
Token sesji to fragment danych (UUID), który jest używany w wywołaniach REST do identyfikowania sesji, czyli serii powiązanych wymian wiadomości. We wszystkich żądaniach dotyczących kafelków 2D i zdjęć Street View musisz uwzględnić token sesji.
Dodajesz go jako wartość parametru session do wszystkich adresów URL żądań.
W interfejsie Map Tiles API token sesji reprezentuje określony zestaw opcji wyświetlania. Oznacza to, że nie musisz przekazywać zestawu opcji wyświetlania z każdym żądaniem kafelka. Możesz używać tego samego tokena sesji na wielu klientach.
Token sesji jest obecnie ważny przez 2 tygodnie od momentu jego wydania, ale może się to zmienić. Czas wygaśnięcia tokena sesji możesz sprawdzić w polu expiry w wiadomości z odpowiedzią.
Żądanie tokena sesji
Aby poprosić o token sesji, wyślij żądanie HTTPS POST do punktu końcowego createSession, jak pokazano w tym przykładzie. Żądanie musisz wysłać z nagłówkiem Content-Type: application/json.
Rodzaj mapy podstawowej. Może to być jedna z tych wartości:
roadmap
Standardowe fragmenty mapy w Mapach Google.
satellite
Zdjęcia satelitarne
terrain
Zdjęcia terenu. Jeśli jako typ mapy wybierzesz terrain, musisz też uwzględnić layerRoadmap typ warstwy (opisany w sekcji Pola opcjonalne).
streetview
panoramy Street View, Więcej informacji znajdziesz w artykule Kafelki Street View.
language
Tag języka IETF określający język, w którym mają być wyświetlane informacje na kafelkach. Na przykład en-US oznacza język angielski używany w Stanach Zjednoczonych.
region
Identyfikator regionu Common Locale Data Repository (2 wielkie litery) reprezentujący fizyczną lokalizację użytkownika. Na przykład: US.
Pola opcjonalne
imageFormat
Określa format pliku do zwrócenia. Prawidłowe wartości to jpeg i png.
Pliki JPEG nie obsługują przezroczystości, dlatego nie zalecamy ich używania w przypadku kafelków nakładkowych. Jeśli nie określisz imageFormat, najlepszy format kafelka zostanie wybrany automatycznie.
scale
Powiększa rozmiar elementów mapy (np. etykiet dróg), zachowując rozmiar kafelka i obszar pokrycia domyślnego kafelka. Zwiększenie skali powoduje też zmniejszenie liczby etykiet na mapie, co ogranicza bałagan. Prawidłowe wartości scale:
scaleFactor1x: wartość domyślna.
scaleFactor2x: podwaja rozmiar etykiet i usuwa etykiety mniejszych obiektów.
scaleFactor4x: czterokrotnie zwiększa rozmiar etykiet i usuwa etykiety mniejszych obiektów.
Poniższe przykłady pokazują, jak skalowanie elementów mapy wpływa na jej wygląd.
Współczynnik skalowania 1x
Współczynnik skalowania 2x
highDpi
Określa, czy mają być zwracane kafelki o wysokiej rozdzielczości. Jeśli współczynnik skalowania zostanie zwiększony, highDpi zostanie użyty do zwiększenia rozmiaru kafelka. Zwykle zwiększenie współczynnika skali powiększa wynikowy fragment do obrazu o tym samym rozmiarze, co obniża jakość. W przypadku highDpi rozmiar wynikowy również się zwiększa, co pozwala zachować jakość. DPI to skrót od Dots per Inch (punkty na cal), a wysoka wartość DPI oznacza, że kafelki są renderowane przy użyciu większej liczby punktów na cal niż zwykle. Jeśli true, liczba pikseli w każdym z wymiarów x i y jest mnożona przez współczynnik skalowania (czyli 2x lub 4x). Obszar objęty kafelkiem pozostanie bez zmian.
Ten parametr działa tylko z wartościami scale 2x lub 4x. Nie ma to wpływu na kafelki w skali 1x.
Współczynnik skalowania 1x
Współczynnik skalowania 2x High DPI
layerTypes
Tablica wartości określająca typy warstw dodanych do mapy. Prawidłowe wartości to:
layerRoadmap
Wymagany, jeśli jako typ mapy podasz terrain. Można ją też opcjonalnie nałożyć na typ mapy satellite. Nie ma wpływu na kafelki z planem rozwoju.
layerStreetview
Wyświetla ulice i lokalizacje z włączoną funkcją Street View, używając niebieskich konturów na mapie.
layerTraffic
Wyświetla aktualne warunki drogowe.
styles
Tablica obiektów w stylu JSON, które określają wygląd i poziom szczegółowości elementów mapy, takich jak drogi, parki i obszary zabudowane. Stylizacja służy do dostosowywania standardowej mapy bazowej Google. Parametr styles jest prawidłowy tylko wtedy, gdy typ mapy to roadmap. Pełną składnię stylu znajdziesz w dokumentacji stylu.
overlay
Wartość logiczna określająca, czy layerTypes ma być renderowany jako osobna nakładka, czy połączony z obrazami podstawowymi. Gdy
true, mapa podstawowa nie jest wyświetlana. Jeśli nie zdefiniowano żadnego elementu layerTypes, ta wartość jest ignorowana.
Na przykład żądanie satellite typu mapy z warstwą layerRoadmap i ustawieniem overlay na false spowoduje wygenerowanie kafelków równoważnych typowi mapy hybrid używanemu w interfejsie Maps JavaScript API (obraz po lewej stronie). Te same typy map i warstw z parametrem overlay ustawionym na true dają przezroczysty kafelek z nakładką mapy, odpowiednio sformatowaną do nakładania na zdjęcia satelitarne (obraz po prawej).
overlay: false
overlay: true
Poniższy kod JSON to przykład typowej treści żądania, która zawiera zarówno pola wymagane, jak i opcjonalne.
Ten przykład zawiera nakładkę, którą można połączyć z obrazami satelitarnymi. Przykład zawiera zarówno mapę drogową, jak i nakładkę widoku ulicy. Wynikowa mapa jest renderowana z nazwami i danymi w języku angielskim, ponieważ jest on używany w Stanach Zjednoczonych.
Odpowiedź tokena sesji
Poniższy kod JSON to przykładowa treść odpowiedzi.
Poniższa lista zawiera definicje pól w treści odpowiedzi.
session
Wartość tokena sesji, którą musisz uwzględnić we wszystkich żądaniach interfejsu Map Tiles API.
expiry
Ciąg znaków zawierający czas (w sekundach od początku epoki), w którym wygasa ważność tokena. Token sesji jest ważny przez 2 tygodnie od momentu jego utworzenia, ale te zasady mogą ulec zmianie bez powiadomienia.
[[["Łatwo zrozumieć","easyToUnderstand","thumb-up"],["Rozwiązało to mój problem","solvedMyProblem","thumb-up"],["Inne","otherUp","thumb-up"]],[["Brak potrzebnych mi informacji","missingTheInformationINeed","thumb-down"],["Zbyt skomplikowane / zbyt wiele czynności do wykonania","tooComplicatedTooManySteps","thumb-down"],["Nieaktualne treści","outOfDate","thumb-down"],["Problem z tłumaczeniem","translationIssue","thumb-down"],["Problem z przykładami/kodem","samplesCodeIssue","thumb-down"],["Inne","otherDown","thumb-down"]],["Ostatnia aktualizacja: 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`."]]
