הכביש 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 דקות תלוי במהירות שבה הנכס נע). אם הנכס הוא נייח, דגימת מיקום אחת מספיקה (אין צורך ליצור מספר שיחות).
כדי למזער את זמן האחזור הכולל, מומלץ להתקשר לשירות 'מגבלת מהירות' אחרי שיצטברו נתונים, במקום לקרוא ל-API בכל פעם התקבל מיקום של נכס לנייד.
למה חלק ממגבלות המהירות או כולן חסרות?
הסיבה השכיחה ביותר להיעדר speedLimits
היא בקשת מהירות מותרת
של מקום שאינו קטע דרך.
הדוגמה שלמעלה משתמשת בגשר ואסקו דה גאמה כדי להדגים מושגים;
הגשר תומך בכביש E90 שחוצה את ריו טג'ו. הגשר
מזהה המקום עצמו כולל את ChIJUzt97ZEwGQ0RM1JzQfqoDtU. קטע הדרך הראשון
בתשובה שלמעלה הוא חלק מכביש E90 ומזהה המקום שלו הוא
ChIJX12duJAwGQ0Ra0d4Oi4jOGE. בבקשה לדוגמה, אם מחליפים את הכביש
מקום מזהה עם מזהה מקום של גשר, אז התשובה תהיה
שתי מגבלות מהירות במערך speedLimits
כי מזהה המקום של הגשר
אינו מתייחס לקטע דרך יחיד. בנוסף, אם לא קיימים
מזהי מקומות שייכים לקטעי דרך, ולכן התגובה לא תכיל
מגבלות מהירות.
כששולחים בקשות להגבלת מהירות באמצעות מזהי מקומות, צריך לוודא שכל מזהה של מקום
מתייחס לקטע דרך ולא לסוג אחר של מקום. מזהי מקומות של
הדרך הטובה ביותר לאחזר קטעי כביש בודדים היא באמצעות snapToRoads
או בקשות nearestRoads
, שכל אחת מהן יכולה להחזיר כמה מזהי מקומות מ:
שיחה אחת.