Sử dụng mã thông báo phiên với API Thẻ thông tin bản đồ
Sử dụng bộ sưu tập để sắp xếp ngăn nắp các trang
Lưu và phân loại nội dung dựa trên lựa chọn ưu tiên của bạn.
Nhà phát triển ở Khu vực kinh tế Châu Âu (EEA)
Mã thông báo phiên là một phần dữ liệu (một UUID) được dùng trong các lệnh gọi REST để xác định một phiên – một chuỗi các hoạt động trao đổi thông báo có liên quan. Bạn phải thêm mã thông báo phiên vào tất cả các yêu cầu đối với Ô 2D và hình ảnh Chế độ xem đường phố.
Bạn đưa mã này vào làm giá trị của một tham số session được thêm vào tất cả các URL yêu cầu.
Trong Map Tiles API, mã thông báo phiên đại diện cho một tập hợp các lựa chọn hiển thị được xác định. Điều này có nghĩa là bạn không cần phải truyền một bộ lựa chọn hiển thị với mỗi yêu cầu về ô. Bạn có thể sử dụng cùng một mã thông báo phiên trên nhiều ứng dụng.
Hiện tại, mã thông báo phiên có hiệu lực trong 2 tuần kể từ thời điểm phát hành, nhưng điều này có thể thay đổi. Bạn luôn có thể kiểm tra thời gian hết hạn của mã thông báo phiên bằng cách xem trường expiry trong thông báo phản hồi.
Yêu cầu mã thông báo phiên
Để yêu cầu mã thông báo phiên, hãy gửi yêu cầu HTTPS POST đến điểm cuối createSession, như trong ví dụ sau. Bạn phải gửi yêu cầu kèm theo tiêu đề Content-Type: application/json.
Chỉ định định dạng tệp cần trả về. Các giá trị hợp lệ là jpeg hoặc png.
Tệp JPEG không hỗ trợ độ trong suốt, do đó, bạn không nên dùng tệp này cho các ô lớp phủ. Nếu bạn không chỉ định imageFormat, thì định dạng phù hợp nhất cho ô sẽ được chọn tự động.
scale
Tăng kích thước của các phần tử trên bản đồ (chẳng hạn như nhãn đường), đồng thời vẫn giữ nguyên kích thước ô và vùng phủ sóng của ô mặc định. Việc tăng tỷ lệ cũng làm giảm số lượng nhãn trên bản đồ, giúp giảm tình trạng lộn xộn. Sau đây là các giá trị scale hợp lệ:
scaleFactor1x: Mặc định.
scaleFactor2x: Tăng gấp đôi kích thước nhãn và xoá các nhãn đối tượng nhỏ.
scaleFactor4x: Tăng gấp 4 lần kích thước nhãn và xoá các nhãn đối tượng nhỏ.
Các ví dụ sau đây minh hoạ hiệu ứng của việc điều chỉnh tỷ lệ các phần tử trên bản đồ.
Hệ số tỷ lệ 1x
Hệ số tỷ lệ 2x
highDpi
Chỉ định xem có trả về các ô có độ phân giải cao hay không. Nếu hệ số tỷ lệ tăng lên, highDpi sẽ được dùng để tăng kích thước của ô. Thông thường, việc tăng hệ số tỷ lệ sẽ phóng to ô kết quả thành một hình ảnh có cùng kích thước, làm giảm chất lượng. Với highDpi, kích thước kết quả cũng tăng lên, duy trì chất lượng. DPI là viết tắt của Dots per Inch (Số điểm trên mỗi inch) và High DPI (DPI cao) có nghĩa là ô kết xuất bằng cách sử dụng nhiều điểm trên mỗi inch hơn bình thường. Nếu true, thì số lượng pixel trong mỗi chiều x và y sẽ được nhân với hệ số tỷ lệ (tức là 2x hoặc 4x). Phạm vi phủ sóng của ô vẫn không thay đổi.
Tham số này chỉ hoạt động với các giá trị scale là 2x hoặc 4x. Chế độ này không ảnh hưởng đến các ô có tỷ lệ 1x.
Hệ số tỷ lệ 1x
Hệ số tỷ lệ 2x DPI cao
layerTypes
Một mảng các giá trị chỉ định các loại lớp được thêm vào bản đồ. Các giá trị hợp lệ là:
layerRoadmap
Bắt buộc nếu bạn chỉ định terrain làm loại bản đồ. Bạn cũng có thể tuỳ ý phủ lớp này lên loại bản đồ satellite. Không ảnh hưởng đến các ô trên lộ trình.
layerStreetview
Cho biết những đường phố và địa điểm có hỗ trợ Chế độ xem đường phố bằng đường viền màu xanh dương trên bản đồ.
layerTraffic
Hiển thị tình trạng giao thông hiện tại.
styles
Một mảng các đối tượng kiểu JSON chỉ định giao diện và mức độ chi tiết của các đối tượng trên bản đồ, chẳng hạn như đường, công viên và khu vực đô thị. Bạn có thể dùng tính năng tạo kiểu để tuỳ chỉnh bản đồ cơ sở tiêu chuẩn của Google. Tham số styles chỉ hợp lệ nếu loại bản đồ là roadmap. Để biết cú pháp đầy đủ về kiểu, hãy xem Tài liệu tham khảo về kiểu.
overlay
Một giá trị boolean chỉ định xem layerTypes có được kết xuất dưới dạng một lớp phủ riêng biệt hay kết hợp với hình ảnh cơ sở. Khi true, bản đồ cơ sở sẽ không xuất hiện. Nếu bạn chưa xác định bất kỳ layerTypes nào, thì giá trị này sẽ bị bỏ qua.
Ví dụ: yêu cầu loại bản đồ satellite có lớp layerRoadmap và overlay được đặt thành false sẽ tạo ra các ô tương đương với loại bản đồ hybrid được dùng trong Maps JavaScript API (hình ảnh bên trái). Cùng một loại bản đồ và lớp có overlay được đặt thành true sẽ tạo ra một ô trong suốt có lớp phủ bản đồ, được tạo kiểu phù hợp để phủ lên hình ảnh vệ tinh (hình ảnh bên phải).
overlay: false
overlay: true
JSON sau đây là ví dụ về một nội dung yêu cầu thông thường chứa cả các trường bắt buộc và không bắt buộc.
Ví dụ này cung cấp một lớp phủ phù hợp để kết hợp với hình ảnh vệ tinh. Ví dụ này chứa cả lớp phủ chế độ xem đường phố và lộ trình. Bản đồ kết quả được hiển thị bằng tên và dữ liệu bằng tiếng Anh, như được nói ở Hoa Kỳ.
Danh sách sau đây chứa định nghĩa về các trường trong nội dung phản hồi.
session
Giá trị mã thông báo phiên mà bạn phải thêm vào tất cả các yêu cầu Map Tiles API.
expiry
Một chuỗi chứa thời gian (tính bằng giây kể từ thời gian bắt đầu hệ thống) mà mã thông báo hết hạn. Mã thông báo phiên có hiệu lực trong 2 tuần kể từ thời điểm tạo, nhưng chính sách này có thể thay đổi mà không cần thông báo.
[null,null,["Cập nhật lần gần đây nhất: 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`."]]
