تنظيم صفحاتك في مجموعات
يمكنك حفظ المحتوى وتصنيفه حسب إعداداتك المفضّلة.
المطوّرون في المنطقة الاقتصادية الأوروبية
رمز الجلسة المميّز هو جزء من البيانات (UUID) يُستخدَم في طلبات REST لتحديد جلسة، وهي سلسلة من عمليات تبادل الرسائل ذات الصلة. يجب تضمين رمز مميّز للجلسة في جميع الطلبات المتعلقة بـ 2D Tiles وصور "التجوّل الافتراضي".
يتم تضمينها كقيمة للمَعلمة session الملحقة بجميع عناوين URL الخاصة بالطلبات.
في Map Tiles API، يمثّل رمز الجلسة مجموعة محدّدة من خيارات العرض. وهذا يعني أنّه ليس عليك تمرير مجموعة من خيارات العرض مع كل طلب لتقسيم الشاشة إلى مربّعات. يمكنك استخدام رمز الجلسة نفسه على عدة أجهزة.
يكون الرمز المميز للجلسة صالحًا حاليًا لمدة أسبوعَين من وقت إصداره، ولكن قد يتغيّر ذلك. يمكنك دائمًا التحقّق من وقت انتهاء صلاحية رمز الجلسة من خلال الاطّلاع على الحقل expiry في رسالة الردّ.
طلب الرمز المميز للجلسة
لطلب رمز مميز للجلسة، أرسِل طلب HTTPS POST إلى نقطة النهاية createSession
كما هو موضّح في المثال التالي. يجب إرسال الطلب مع عنوان Content-Type: application/json.
نوع الخريطة الأساسية يمكن أن تكون هذه القيمة إحدى القيم التالية:
roadmap
مربّعات الخرائط المرسومة العادية في "خرائط Google"
satellite
صور القمر الصناعي:
terrain
صور التضاريس عند اختيار terrain كنوع الخريطة، يجب أيضًا تضمين نوع الطبقة layerRoadmap (الموضّح في قسم الحقول الاختيارية).
streetview
صور بانورامية في "التجوّل الافتراضي" لمزيد من المعلومات، يُرجى الاطّلاع على مربّعات Street View.
language
علامة لغة IETF تحدّد اللغة المستخدَمة لعرض المعلومات على المربّعات. على سبيل المثال، يشير الرمز en-US إلى اللغة الإنجليزية كما يتم التحدّث بها في الولايات المتحدة.
تحدّد هذه السمة تنسيق الملف الذي سيتم عرضه. القيمتان الصالحتان هما jpeg أو png.
لا تتوافق ملفات JPEG مع الشفافية، لذا لا يُنصح باستخدامها مع مربّعات التراكب. إذا لم تحدّد imageFormat، سيتم تلقائيًا اختيار أفضل تنسيق للمربّع.
scale
تكبير حجم عناصر الخريطة (مثل تصنيفات الطرق)، مع الاحتفاظ بحجم المربّع ومساحة التغطية للمربّع التلقائي تؤدي زيادة المقياس أيضًا إلى تقليل عدد التصنيفات على الخريطة، ما يقلّل من الازدحام. في ما يلي قيم scale الصالحة:
scaleFactor1x: القيمة التلقائية
scaleFactor2x: يضاعف حجم التصنيف ويزيل تصنيفات المعالم الثانوية.
scaleFactor4x: يضاعف حجم التصنيف أربع مرات ويزيل تصنيفات المعالم الثانوية.
توضّح الأمثلة التالية تأثير تغيير حجم عناصر الخريطة.
عامل التحجيم 1x
عامل التحجيم 2x
highDpi
تحدّد هذه السمة ما إذا كان سيتم عرض مربّعات بدقة عالية. في حال زيادة عامل المقياس، يتم استخدام highDpi لزيادة حجم المربّع. في العادة، تؤدي زيادة عامل القياس إلى تكبير المربّع الناتج إلى صورة بالحجم نفسه، ما يؤدي إلى خفض الجودة. باستخدام highDpi، يزداد الحجم الناتج أيضًا، ما يحافظ على الجودة. يشير مصطلح DPI إلى "النقاط في البوصة"، ويعني مصطلح High DPI أنّ المربّع يتم عرضه باستخدام عدد أكبر من النقاط في البوصة مقارنةً بالحالة العادية. إذا كانت القيمة true، يتم ضرب عدد وحدات البكسل في كل من البُعدَين x وy في عامل القياس (أي 2x أو 4x). لن تتغيّر منطقة تغطية البلاطة.
لا تعمل هذه المَعلمة إلا مع القيم scale التي تبلغ 2x أو 4x. ليس لهذا الإعداد أي تأثير في المربّعات ذات المقياس 1x.
عامل التحجيم 1x
عامل التحجيم 2x High DPI
layerTypes
مصفوفة من القيم تحدّد أنواع الطبقات التي تمت إضافتها إلى الخريطة. القيم الصالحة هي:
layerRoadmap
مطلوبة إذا حدّدت terrain كنوع الخريطة. يمكن أيضًا عرضها بشكل اختياري
على نوع الخريطة satellite. لا يؤثّر في مربّعات خارطة الطريق.
layerStreetview
تعرض الشوارع والمواقع الجغرافية التي تتوفّر فيها ميزة "التجوّل الافتراضي" باستخدام خطوط زرقاء على الخريطة.
layerTraffic
تعرِض هذه الطبقة حالة حركة المرور الحالية.
styles
مصفوفة من عناصر نمط JSON التي تحدد المظهر ومستوى التفاصيل الخاصة بميزات الخريطة، مثل الطرق والمتنزّهات والمناطق المبنية يتم استخدام التنسيق لتخصيص خريطة Google الأساسية العادية. لا تكون المَعلمة styles صالحة إلا إذا كان نوع الخريطة roadmap. للاطّلاع على بنية النمط الكاملة، يُرجى الرجوع إلى
مرجع الأنماط.
overlay
قيمة منطقية تحدّد ما إذا كان يجب عرض layerTypes كطبقة منفصلة أو دمجها مع الصور الأساسية. عندما تكون قيمة
true، لا يتم عرض الخريطة الأساسية. إذا لم تحدّد أي layerTypes، سيتم تجاهل هذه القيمة.
على سبيل المثال، سيؤدي طلب نوع خريطة satellite مع طبقة layerRoadmap وضبط overlay على false إلى عرض مربّعات مكافئة لنوع الخريطة hybrid المستخدَم في Maps JavaScript API (الصورة على اليمين). يؤدي استخدام أنواع الخرائط والطبقات نفسها مع ضبط overlay على true إلى إنشاء مربّع شفاف مع خريطة متراكبة، ويتم تنسيقه بشكل مناسب للتراكب على صور الأقمار الصناعية (الصورة على اليسار).
overlay: false
overlay: true
في ما يلي مثال على نص طلب نموذجي يحتوي على الحقول المطلوبة والاختيارية.
يقدّم هذا المثال طبقة متراكبة مناسبة للدمج مع صور الأقمار الصناعية. يحتوي المثال على خارطة طريق وطبقة عرض الشارع. يتم عرض الخريطة الناتجة مع الأسماء والبيانات باللغة الإنجليزية، كما يتم التحدث بها في الولايات المتحدة.
تحتوي القائمة التالية على تعريفات للحقول في نص الرد.
session
قيمة رمز مميّز للجلسة يجب تضمينها في جميع طلبات Map Tiles API.
expiry
سلسلة تتضمّن الوقت (بالثواني منذ بدء حساب الفترة) الذي تنتهي فيه صلاحية الرمز المميّز. يكون رمز الجلسة صالحًا لمدة أسبوعَين من وقت إنشائه، ولكن قد تتغير هذه السياسة بدون إشعار.
تاريخ التعديل الأخير: 2025-08-29 (حسب التوقيت العالمي المتفَّق عليه)
[null,null,["تاريخ التعديل الأخير: 2025-08-29 (حسب التوقيت العالمي المتفَّق عليه)"],[[["\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`."]]
