세션 토큰은 REST 호출에서 세션(일련의 관련 메시지 교환)을 식별하는 데 사용되는 데이터(UUID)입니다. 2D 타일 및 스트리트 뷰 이미지에 대한 모든 요청에 세션 토큰을 포함해야 합니다.
모든 요청 URL에 추가된 session 매개변수의 값으로 포함합니다.
Map Tiles API에서 세션 토큰은 정의된 표시 옵션 집합을 나타냅니다. 즉, 각 타일 요청과 함께 디스플레이 옵션 세트를 전달하지 않아도 됩니다. 여러 클라이언트에서 동일한 세션 토큰을 사용할 수 있습니다.
세션 토큰은 현재 발급 시간으로부터 2주 동안 유효하지만 변경될 수 있습니다. 응답 메시지의 expiry 필드를 확인하여 세션 토큰의 만료 시간을 언제든지 확인할 수 있습니다.
세션 토큰 요청
세션 토큰을 요청하려면 다음 예와 같이 createSession 엔드포인트에 HTTPS POST 요청을 보냅니다. Content-Type: application/json 헤더와 함께 요청을 보내야 합니다.
반환할 파일 형식을 지정합니다. 유효한 값은 jpeg 또는 png입니다.
JPEG 파일은 투명도를 지원하지 않으므로 오버레이 타일에는 권장되지 않습니다. imageFormat를 지정하지 않으면 타일에 가장 적합한 형식이 자동으로 선택됩니다.
scale
기본 타일의 타일 크기와 범위 영역을 유지하면서 지도 요소 (예: 도로 라벨)의 크기를 확대합니다. 축척을 늘리면 지도에 표시되는 라벨 수도 줄어들어 어수선함이 줄어듭니다. 다음 값은 유효한 scale 값입니다.
scaleFactor1x: 기본값입니다.
scaleFactor2x: 라벨 크기를 두 배로 늘리고 사소한 기능 라벨을 삭제합니다.
scaleFactor4x: 라벨 크기를 4배로 늘리고 사소한 기능 라벨을 삭제합니다.
다음 예에서는 지도 요소의 크기 조절 효과를 보여줍니다.
배율 1x
배율 2x
highDpi
고해상도 타일을 반환할지 여부를 지정합니다. 배율이 증가하면 highDpi를 사용하여 타일 크기를 늘립니다. 일반적으로 배율을 높이면 결과 타일이 동일한 크기의 이미지로 확대되어 품질이 저하됩니다. highDpi를 사용하면 결과 크기도 증가하여 품질이 유지됩니다. DPI는 인치당 도트 수를 나타내며, DPI가 높다는 것은 타일이 정상보다 인치당 더 많은 도트를 사용하여 렌더링된다는 의미입니다. true인 경우 x 및 y 각 차원의 픽셀 수가 배율 인자 (즉, 2x 또는 4x)로 곱해집니다. 타일의 커버리지 영역은 변경되지 않습니다.
이 매개변수는 scale 값이 2x 또는 4x인 경우에만 작동합니다. 1배 스케일 타일에는 영향을 미치지 않습니다.
배율 1x
배율 2x 고해상도
layerTypes
지도에 추가된 레이어 유형을 지정하는 값의 배열입니다. 유효한 값은 다음과 같습니다.
layerRoadmap
지도 유형을 terrain로 지정하는 경우 필수입니다. satellite 지도 유형에 선택적으로 오버레이할 수도 있습니다. 로드맵 타일에는 영향을 미치지 않습니다.
layerStreetview
지도에 스트리트 뷰가 지원되는 거리와 위치를 파란색 윤곽선으로 표시합니다.
layerTraffic
현재 교통 상황을 표시합니다.
styles
도로, 공원, 시가지와 같은 지도 지형지물의 모양과 세부정보 수준을 지정하는 JSON 스타일 객체의 배열입니다. 스타일 지정은 표준 Google 기본 지도를 맞춤설정하는 데 사용됩니다. styles 파라미터는 지도 유형이 roadmap인 경우에만 유효합니다. 전체 스타일 구문은 스타일 참조를 참고하세요.
overlay
layerTypes를 별도의 오버레이로 렌더링할지 아니면 기본 이미지와 결합할지를 지정하는 불리언 값입니다. true인 경우 기본 지도가 표시되지 않습니다. layerTypes을 정의하지 않은 경우 이 값은 무시됩니다.
예를 들어 layerRoadmap 레이어가 있는 satellite 지도 유형을 요청하고 overlay를 false로 설정하면 Maps JavaScript API에서 사용되는 hybrid 지도 유형과 동일한 타일이 생성됩니다 (왼쪽 이미지). overlay이 true로 설정된 동일한 지도 및 레이어 유형은 위성 이미지 위에 오버레이되도록 적절하게 스타일이 지정된 지도 오버레이가 있는 투명 타일을 생성합니다(오른쪽 이미지).
[null,null,["최종 업데이트: 2025-08-29(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`."]]
