הפונקציה 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– מחרוזת שמכילה אזהרה שגלויה למשתמשים.
דוגמה לבקשה עם נתיב
הבקשה הזו מקבלת את מגבלת המהירות של כל מקטע כביש הקרוב ביותר לזוגות קו הרוחב/קו האורך שצוינו, במסלול שחוצה את גשר Vasco da Gama בליסבון, פורטוגל.
בקשה
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 חסר היא בקשה למגבלת מהירות של מקום שאינו מקטע כביש.
בדוגמה שלמעלה נעשה שימוש בגשר Vasco da Gama כדי להמחיש מושגים. הגשר תומך בכביש E90 שחוצה את Rio Tejo. למנהרה עצמה יש מזהה מקום בשם ChIJUzt97ZEwGQ0RM1JzQfqoDtU. מקטע הכביש הראשון בתגובה שלמעלה הוא חלק מכביש E90 ומזהה המקום שלו הוא ChIJX12duJAwGQ0Ra0d4Oi4jOGE. בבקשה לדוגמה, אם מחליפים את מזהה המיקום של הכביש במזהה המיקום של הגשר, בתגובה יופיעו רק שני מגבלות מהירות במערך speedLimits כי מזהה המיקום של הגשר לא מתייחס לקטע דרך ספציפי. בנוסף, אם אף אחד ממזהי המקומות לא מייצג קטעי כביש, התגובה לא תכלול מגבלות מהירות.
כששולחים בקשות להגבלת מהירות באמצעות מזהי מיקומים, חשוב לוודא שכל מזהה מיקום מתייחס לקטע דרך ולא לסוג אחר של מקום. מומלץ לאחזר מזהי מקומות של קטעי כביש ספציפיים באמצעות בקשות snapToRoads או nearestRoads, שכל אחת מהן יכולה להחזיר כמה מזהי מקומות בקריאה אחת.