שימוש באסימוני סשנים עם API של אריחי מפה

אסימון סשן הוא קטע נתונים (UUID) שמשמש בקריאות REST לזיהוי סשן – סדרה של החלפות הודעות קשורות. חובה לכלול אסימון סשן בכל הבקשות לתמונות 2D ותמונות Street View. צריך לכלול אותו כערך של פרמטר session שמצורף לכל כתובות ה-URL של הבקשות.

ב-Map Tiles API, טוקן סשן מייצג קבוצה מוגדרת של אפשרויות תצוגה. המשמעות היא שאין צורך להעביר קבוצה של אפשרויות תצוגה עם כל בקשה לשימוש באריח. אפשר להשתמש באותו אסימון סשן במספר לקוחות. אסימון הסשן בתוקף למשך שבועיים ממועד ההנפקה, אבל זה עשוי להשתנות. תמיד אפשר לבדוק את זמן התפוגה של אסימון הסשן על ידי בדיקת השדה expiry בהודעת התגובה.

בקשה לאסימון סשן

כדי לבקש אסימון סשן, שולחים בקשת POST ב-HTTPS לנקודת הקצה createSession, כפי שמוצג בדוגמה הבאה. צריך לשלוח את הבקשה עם כותרת Content-Type: application/json.

curl -X POST -d '{
  "mapType": "streetview",
  "language": "en-US",
  "region": "US"
}' \
-H 'Content-Type: application/json' \
"https://tile.googleapis.com/v1/createSession?key=YOUR_API_KEY"

שדות חובה

mapType

סוג המפה הבסיסית. הערך הזה יכול להיות אחד מהערכים הבאים:

roadmap
קטעי המפה הרגילים של מפות Google שצוירו.
satellite
צילומי לוויין.
terrain
תמונות של פני השטח. כשבוחרים באפשרות terrain כסוג המפה, צריך לכלול גם את סוג השכבה layerRoadmap (המתואר בקטע שדות אופציונליים).
streetview
תמונות פנורמיות ב-Street View. למידע נוסף, ראו תמונות Street View.
language

תג שפה של IETF שמציין את השפה שמשמשת להצגת מידע במשבצות. לדוגמה, הערך en-US מציין את השפה האנגלית המדוברת בארצות הברית.

region

מזהה אזור של Common Locale Data Repository (שתי אותיות רישיות) שמייצג את המיקום הפיזי של המשתמש. לדוגמה, US.

שדות אופציונליים

imageFormat
קביעת הפורמט של הקובץ שיוחזר. הערכים החוקיים הם jpeg או png. קבצי JPEG לא תומכים בשקיפות, ולכן לא מומלץ להשתמש בהם כשכבות-על. אם לא מציינים את הפרמטר imageFormat, המערכת בוחרת באופן אוטומטי את הפורמט הטוב ביותר לכרטיס.
scale

הגדלת הגודל של רכיבי המפה (כמו תוויות של כבישים), תוך שמירה על גודל המשבצת ועל אזור הכיסוי של המשבצת שמוגדרת כברירת מחדל. הגדלת קנה המידה מפחיתה גם את מספר התוויות במפה, וכך מפחיתה את העומס. הערכים הבאים הם ערכים חוקיים של scale:

  • scaleFactor1x: ברירת המחדל.
  • scaleFactor2x: הגדלת גודל התווית והסרת תוויות של תכונות משניות.
  • scaleFactor4x: גודל התווית יורחב לארבעה והסרת תוויות משניות של תכונות.

הדוגמאות הבאות ממחישות את ההשפעה של שינוי קנה המידה של רכיבי מפה.

גורם קנה מידה 1x קנה מידה 2x
מפה שמציגה גורם קנה מידה 1x מפה שבה מוצג גורם קנה מידה 2
highDpi
הגדרה שמציינת אם להחזיר משבצות ברזולוציה גבוהה. אם מתאם השינוי גדל, highDpi משמש להגדלת גודל המשבצת. בדרך כלל, הגדלת גורם ההתאמה מגדילה את המשבצת שנוצרת לתמונה באותו גודל, וכתוצאה מכך האיכות יורדת. כשמשתמשים ב-highDpi, גם הגודל של התמונה המעובדת גדל, תוך שמירה על האיכות. DPI הוא ראשי תיבות של 'נקודות לאינץ'', והמשמעות של DPI גבוה היא שהעיבוד של האריח מתבצע באמצעות יותר נקודות לאינץ' מהרגיל. אם הערך הוא true, מספר הפיקסלים בכל אחד מהמאפיינים x ו-y מוכפל בגורם קנה המידה (כלומר 2x או 4x). אזור הכיסוי של המשבצת לא ישתנה. הפרמטר הזה פועל רק עם ערכי scale של 2x או 4x. היא לא משפיעה על משבצות בקנה מידה של 1x.
גורם קנה מידה 1x גורם לקביעת קנה מידה 2x DPI גבוה
מפה שמוצגת ברזולוציה רגילה מפה שמוצגת ברזולוציית DPI גבוהה פי 2
layerTypes

מערך ערכים שמציין את סוגי השכבות שנוספו למפה. הערכים החוקיים הם:

layerRoadmap
חובה אם מציינים את סוג המפה terrain. אפשר גם להציג שכבת-על על סוג המפה satellite. אין לכך השפעה על משבצות מפת הדרכים.
layerStreetview
רחובות ומיקומים שתכונת Street View זמינה בהם מוצגים במפה באמצעות קווים כחולים.
layerTraffic
הצגת תנאי התנועה הנוכחיים.
styles

מערך של אובייקטים בסגנון JSON שמציינים את המראה ורמת הפירוט של תכונות המפה, כמו כבישים, פארקים ואזורים בנויים. אפשר להשתמש בסגנון כדי להתאים אישית את מפת הבסיס הרגילה של Google. הפרמטר styles תקף רק אם סוג המפה הוא roadmap. התחביר המלא של הסגנון מפורט בחומר העזר בנושא סגנונות.

overlay

ערך בוליאני שמציין אם צריך לעבד את layerTypes כשכבת-על נפרדת או לשלב את התמונה הבסיסית. כשהערך הוא true, המפה הבסיסית לא מוצגת. אם לא הגדרתם layerTypes, המערכת תתעלם מהערך הזה.

לדוגמה, בקשה לסוג מפה satellite עם שכבה layerRoadmap, כשהערך של overlay מוגדר ל-false, מובילה ליצירת משבצות שדומות לסוג המפה hybrid שמשמש בממשק API של JavaScript במפות Google (בתמונה הימנית). אותם סוגי מיפוי ושכבות שהוגדרו ב-overlay לערך true יוצרים משבצת שקופה עם שכבת-על של מפה, שמעוצבת בהתאם לשכבת-על מעל צילומי לוויין (בתמונה משמאל).

overlay: false overlay: true
שכבת-העל הוגדרה כ-False שכבת-העל הוגדרה כ-true

ה-JSON הבא הוא דוגמה לגוף בקשה טיפוסי שמכיל שדות חובה וגם שדות אופציונליים.

{
  "mapType": "satellite",
  "language": "en-US",
  "region": "us",
  "layerTypes": [ "layerRoadmap", "layerStreetview" ],
  "overlay":  true,
  "scale": "scaleFactor1x",
  "styles": [
    {
      "stylers": [
        { "hue": "#00ffe6" },
        { "saturation": -20 }
      ]
    },{
      "featureType": "road",
      "elementType": "geometry",
      "stylers": [
        { "lightness": 100 },
        { "visibility": "simplified" }
      ]
    }
  ]
}

בדוגמה הזו מוצג שכבת-על שמתאימה לשילוב עם תמונות לוויין. הדוגמה כוללת גם מפת דרכים וגם שכבת-על של Street View. המפה שמתקבלת מוצגת עם שמות ונתונים בשפה האנגלית, כפי שהיא מדוברת בארצות הברית.

apiOptions: מערך ערכים שמציין אפשרויות נוספות להחלה. האפשרויות הנתמכות הן:

תגובה לטוקן הסשן

קובץ ה-JSON הבא הוא דוגמה לגוף תגובה.

{
  "session": "IgAAAHGU9jnAU4KOAfwY3Bcd6eH_WxQsyocSBAdUnAr9pnvTTNXtF9c_27RBo94ytEXTDg",
  "expiry": "1361828036",
  "tileWidth": 256,
  "tileHeight": 256,
  "imageFormat": "png"
}

ברשימה הבאה מפורטות ההגדרות של השדות בגוף התגובה.

session
ערך של אסימון סשן שצריך לכלול בכל הבקשות ל-Map Tiles API.
expiry
מחרוזת שמכילה את השעה (בשניות מאז תחילת התקופה של זמן מערכת) שבה יפוג התוקף של האסימון. אסימון סשן תקף למשך שבועיים ממועד היצירה שלו, אבל המדיניות הזו עשויה להשתנות ללא הודעה מוקדמת.
tileWidth
הרוחב של המשבצות, שנמדד בפיקסלים.
tileHeight
הגובה של המשבצות, שנמדד בפיקסלים.
imageFormat
פורמט התמונה, יכול להיות png או jpeg.