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

הפונקציה 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 ומזהה המקום שלו הוא ChIJX12duJAwGQ0Ra0d4Oi4jOGE. בדוגמה של הבקשה, אם מחליפים את מזהה המקום של הכביש במזהה המקום של הגשר, בתשובה יהיו רק שתי הגבלות מהירות במערך speedLimits, כי מזהה המקום של הגשר לא מתייחס לקטע כביש ספציפי. בנוסף, אם אף אחד ממזהי המקומות לא מתייחס לקטע דרך, התשובה לא תכלול הגבלות מהירות.

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

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

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