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

הפונקציה 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"
    }
  ]
}

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

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

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

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

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

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

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