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

הפונקציה 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 מחזירה את המהירות המקסימלית המותרת שפורסמה לרכבים בלבד.