מגבלות מהירות

הערה: שירות 'מגבלת מהירות' זמין לכל הלקוחות שיש להם רישיון למעקב אחרי נכסים. לקוחות של תוכנית הפרימיום של הפלטפורמה של מפות Google שעברו לתמחור של תשלום לפי שימוש, התכונה 'מגבלת מהירות' נשארת פעילה בפרויקטים עם יכולות מעקב אחר נכסים (פרויקטים עם מזהה פרויקט בפורמט Maps-asset-xxx).

הפונקציה Roads API מחזירה את מגבלת המהירות המותרת בקטע דרך נתון. במקרה של קטעי כביש עם מגבלות מהירות משתנות, מגבלת המהירות למקטע מוחזרת כברירת מחדל.

אי אפשר להבטיח את דיוק הנתונים של מגבלת המהירות שמוחזרים על ידי Roads API. נתוני מגבלת המהירות לא מוצגים בזמן אמת, ויכול להיות שהם יהיו משוערים, לא מדויקים, חלקיים ו/או לא מעודכנים. בפרטי הכיסוי תוכלו לראות באילו אזורים יש נתונים על מגבלת המהירות.

בקשות

את הבקשה להגבלת מהירות צריך לשלוח דרך HTTPS, בפורמט הבא:

https://roads.googleapis.com/v1/speedLimits?parameters&key=YOUR_API_KEY

שימוש בפרמטר

פרמטרים נדרשים

• הפרמטר path או הפרמטר placeId.
  • path – רשימה של עד 100 זוגות של קווי אורך ורוחב שמייצגים נתיב. יש להפריד בין הערכים של קו הרוחב וקו האורך באמצעות פסיקים. צמדים של קו רוחב/קו אורך צריכים להיות מופרדים באמצעות הקו אנכי: '|'. כשמציינים את הפרמטר path, ה-API קודם מחבר את הנתיב לכביש עם הכי הרבה תנועה (כפי שקורה בבקשה ל-snapToRoads), ואז קובע את מגבלת המהירות של קטע הכביש הרלוונטי. אם לא רוצים שה-API יצמיד את הנתיב, צריך להעביר את הפרמטר placeId כמו שמוסבר בהמשך. בדוגמה הבאה מוצג הפרמטר path עם שלושה זוגות של קו רוחב/קו אורך: path=60.170880,24.942795|60.170879,24.942796|60.170877,24.942796.
  • placeId – מזהי המקומות שמייצגים קטע דרך אחד או יותר. חשוב לוודא שכל מזהה מקום מתייחס לקטע דרך ולא לסוג אחר של מקום. בכל בקשה אפשר להעביר עד 100 מזהי מקומות. ה-API לא מבצע צילום כבישים במזהי המקומות שסופקו. התגובה כוללת מגבלת מהירות לכל מזהה מקום בבקשה. אפשר לשלוח בקשה snapToRoads או nearestRoads כדי למצוא את מזהי המקומות הרלוונטיים, ואז לציין אותם כקלט לבקשת speedLimits. בדוגמה הבאה מוצג הפרמטר placeId עם שני מזהי מקומות: placeId=ChIJX12duJAwGQ0Ra0d4Oi4jOGE&placeId=ChIJLQcticc0GQ0RoiNZJVa5GxU
• key – מפתח ה-API של האפליקציה שלך. האפליקציה צריכה להזדהות בכל פעם שהיא שולחת בקשה ל-Roads API, על ידי הכללת מפתח API לכל בקשה. איך מקבלים מפתח

פרמטרים אופציונליים

• units – האם להחזיר מגבלות מהירות בקילומטרים או במיילים לשעה. אפשר להגדיר אותו ל-KPH או ל-MPH. ברירת המחדל היא KPH.

תשובות

הרכיבים הבאים עשויים להופיע בתשובה speedLimits:

• speedLimits – מערך מטא-נתונים של כבישים. כל רכיב מורכב מהשדות הבאים:
  • placeId – מזהה ייחודי של מקום. כל מזהי המקומות שמוחזרים על ידי Roads API תואמים למקטעי הכביש.
  • speedLimit – המהירות המותרת בקטע הכביש הזה.
  • units – הפונקציה מחזירה KPH או MPH.
• snappedPoints – מערך של נקודות מוצמדות. המערך הזה קיים רק אם הבקשה הכילה פרמטר path. כל נקודה מורכבת מהשדות הבאים:
  • location — מכיל ערך latitude ו-longitude.
  • originalIndex – מספר שלם שמציין את הערך התואם בבקשה המקורית. כל ערך בבקשה צריך להיות ממופה לערך מוצמד בתגובה. הערכים האלה נוספו לאינדקס מ-0, כך שנקודה עם originalIndex של 4 תהיה הערך המוצמד של קו הרוחב/קו האורך החמישי שמועבר לפרמטר path.
  • placeId – מזהה ייחודי של מקום. כל מזהי המקומות שמוחזרים על ידי Roads API תואמים למקטעי הכביש. אפשר לעבור את placeId בבקשת מגבלות מהירות כדי לקבוע את מגבלת המהירות לאורך קטע הכביש הזה.
• warning_message – מחרוזת שמכילה אזהרה שמוצגת למשתמש.

דוגמה לבקשה באמצעות נתיב

הבקשה הזו מקבלת את מגבלת המהירות לכל קטע כביש הקרוב ביותר לצמדי קו הרוחב/קו האורך שצוינו בנתיב שחוצה את גשר ואסקו דה גאמה בליסבון שבפורטוגל.

שליחת בקשה

https://roads.googleapis.com/v1/speedLimits?path=38.75807927603043,-9.03741754643809|38.6896537,-9.1770515|41.1399289,-8.6094075&key=YOUR_API_KEY

תגובה

{
  speedLimits:
  [
    {
      placeId: "ChIJX12duJAwGQ0Ra0d4Oi4jOGE",
      speedLimit: 105,
      units: "KPH"
    },
    {
      placeId: "ChIJLQcticc0GQ0RoiNZJVa5GxU",
      speedLimit: 70,
      units: "KPH"
    },
    {
      placeId: "ChIJJ4vQRudkJA0RpednU70A-5M",
      speedLimit: 55,
      units: "KPH"
    }
  ],
  snappedPoints:
  [
    {
      location:
      {
        latitude: 38.75807927603043,
        longitude: -9.037417546438084
      },
      originalIndex: 0,
      placeId: "ChIJX12duJAwGQ0Ra0d4Oi4jOGE"
    },
    {
      location:
      {
        latitude: 38.689653701836896,
        longitude: -9.177051486847693
      },
      originalIndex: 1,
      placeId: "ChIJLQcticc0GQ0RoiNZJVa5GxU"
    },
    {
      location:
      {
        latitude: 41.13993011767777,
        longitude: -8.609400794783655
      },
      originalIndex: 2,
      placeId: "ChIJJ4vQRudkJA0RpednU70A-5M"
    }
  ],
  warningMessage: "Input path is too sparse. You should provide a path where consecutive points are closer to each other. Refer to the 'path' parameter in Google Roads API documentation."
}

שימו לב להודעת האזהרה לגבי צבירת נקודות בתשובה שלמעלה. אם מבקשים מגבלות מהירות למקטעי הכביש הקרובים ביותר בנקודות שרירותיות, צריך להפעיל את speedLimits עם מזהי מקומות שאוחזרו מנקודת הקצה nearestRoads.

דוגמה לבקשה עם מזהי מקומות

במקום להשתמש בצמדים של קו רוחב/קו אורך, אתם יכולים להעביר את מזהי המקומות של מקטעי הכביש. אנחנו ממליצים לקבל מזהי מקומות של קטעי כביש באמצעות בקשות snapToRoads או nearestRoads. כשמעבירים את מזהי המקומות, ה-API מחזיר את מגבלת המהירות של קטע הדרך שמיוצג על ידי כל מזהה מקום. ה-API לא מחיל תמונות כבישים על מזהי המקומות שסופקו.

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

שליחת בקשה

https://roads.googleapis.com/v1/speedLimits?placeId=ChIJX12duJAwGQ0Ra0d4Oi4jOGE&placeId=ChIJLQcticc0GQ0RoiNZJVa5GxU&placeId=ChIJJ4vQRudkJA0RpednU70A-5M&key=YOUR_API_KEY

תגובה

{
  "speedLimits": [
    {
      placeId: "ChIJX12duJAwGQ0Ra0d4Oi4jOGE",
      speedLimit: 105,
      units: "KPH"
    },
    {
      placeId: "ChIJLQcticc0GQ0RoiNZJVa5GxU",
      speedLimit: 70,
      units: "KPH"
    },
    {
      placeId: "ChIJJ4vQRudkJA0RpednU70A-5M",
      speedLimit: 55,
      units: "KPH"
    }
  ]
}

המלצות שימוש

כדי למזער את כמות הקריאות לשירות Speed Limit, מומלץ לדגום את מיקומי הנכסים במרווחי זמן של 5 עד 15 דקות (הערך המדויק תלוי במהירות שבה הנכס נע). אם הנכס הוא נייח, מספיק דגימת מיקום אחת (לא צריך לבצע כמה קריאות).

כדי לצמצם את זמן האחזור הכולל, מומלץ לשלוח קריאה לשירות Speed Limit אחרי שצוברים נתונים, במקום לשלוח קריאה ל-API בכל פעם שמתקבל מיקום של נכס לנייד.

למה חלק ממגבלות המהירות או כולן חסרות?

הסיבה השכיחה ביותר להיעדר speedLimits היא בקשת מהירות מותרת של מקום שאינו קטע כביש.

הדוגמה שלמעלה משתמשת בגשר ואסקו דה גמה כדי להמחיש מושגים. הגשר תומך בכביש E90 שחוצה את ריו טז'ו. לגשר עצמו יש מזהה מקום ChIJUzt97ZEwGQ0RM1JzQfqoDtU. קטע הכביש הראשון בתשובה שלמעלה הוא חלק מכביש E90 ומזהה המקום שלו הוא CheIJX12duJAwGQ0Ra0d4Oi4jOGE. בבקשה לדוגמה, אם מחליפים את המזהה של מקום הכביש במזהה המקום של הגשר, בתשובה יהיו רק שתי הגבלות מהירות במערך speedLimits כי מזהה המקום של הגשר לא מתייחס לקטע כביש ספציפי. בנוסף, אם אף אחד ממזהי המקומות לא מיועד לקטעי כביש, התגובה לא תכלול מגבלות מהירות.

כששולחים בקשות להגבלת מהירות באמצעות מזהי מקומות, צריך לוודא שכל מזהה מקום מתייחס לקטע כביש ולא לסוג אחר של מקום. הדרך הטובה ביותר לאחזר מזהי מקומות של קטעי כביש ספציפיים היא באמצעות בקשות snapToRoads או nearestRoads, שכל אחת מהן יכולה להחזיר מספר מזהי מקומות משיחה אחת.