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

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

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

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

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

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

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

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

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

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

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