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