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

הפונקציה 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=ChIJs5ydyTiuEmsR0fRSlU0C7k0&placeId=ChIJW__r4ERXzpQRgkeRL6P0m3Y

  • ‫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"
    }
  ]
}

המלצות לשימוש

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

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

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

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

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

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

מה קורה אם בקטע כביש מסוים יש הגבלות מהירות שונות למכוניות ולמשאיות?

הפונקציה Roads API מחזירה את המהירות המקסימלית המותרת שמוצגת רק לרכבים.