מושגים מרכזיים

כדי ליצור איזוכרון, צריך לספק ל-API נקודת מוצא, אמצעי הגעה כמו נהיגה, רכב דו-גלגלי, רכיבה על אופניים או הליכה, ומגבלת זמן. אתם יכולים גם לשנות את העדפות המסלול ואת המראה של המצולע שנוצר.

אמצעי הגעה

משתמשים בפרמטר החובה travelMode (travel_mode) כדי לציין את אמצעי התחבורה:

• ‫DRIVE: מחשב את הנגישות של רכב נוסעים בכבישים שניתן לנסוע בהם, על סמך מגבלות המהירות שמופיעות בשלטים, היררכיית הכבישים, קנסות על פניות ו(אופציונלי) מצב התנועה בזמן אמת.
• ‫TWO_WHEELER: חישוב הנגישות של רכב דו-גלגלי ממונע (כמו אופנוע או קטנוע) באמצעות כללי גישה לכבישים שספציפיים לאמצעי התחבורה הזה, ומהירויות נמוכות יותר מאשר DRIVE בכבישים מהירים. לכן, בדרך כלל איזוכרון של TWO_WHEELER מכסה שטח גדול יותר מ-BICYCLE אבל קטן יותר מ-DRIVE לאורך כבישים מהירים.
• ‫BICYCLE: מחשב את קלות ההגעה לרוכבי אופניים ברחובות, בנתיבי אופניים ובשבילים משותפים שנגישים לאופניים, עם מהירויות שמותאמות לסוג הדרך ולשיפוע, לא כולל כבישים מהירים וכבישים מהירים עם גישה מבוקרת.
• ‫WALK: חישוב הנגישות להולכי רגל לאורך מדרכות, שבילים, מסלולים ורחובות שנגישים להולכי רגל, עם מהירות הליכה שמותאמת לשיפוע. כשמדובר בהולכי רגל, המערכת מתעלמת מהגבלות על כלי רכב בכבישים חד-סטריים.

טווח זמן

האילוץ העיקרי שאתם מספקים לשירות הוא travelDuration (travel_duration), שמגדיר את טווח הזמן לחישוב.

• משך מינימלי ומקסימלי: משך הזמן חייב להיות לפחות "1s" (שנייה אחת). ערכים של אפס ("0s"), משכי זמן שליליים ומשכי זמן של פחות משנייה אחת (כמו "0.5s") מחזירים שגיאת 400 INVALID_ARGUMENT. ה-API תומך בזמן הגעה מקסימלי של 3,600 שניות (שעה אחת) למצבים DRIVE ו-TWO_WHEELER, ו-7,200 שניות (שעתיים) למצבים WALK ו-BICYCLE.
• מינימום שטח למצולע: ה-API ממיר את קטעי הכביש שהגיעו אליהם לתאי רשת מרחביים, ולכן משכי זמן קצרים מאוד מחזירים מצולע קטן שמכסה את תאי הרשת מסביב לנקודת המוצא שהוצמדה.
• ביצועים: זמן החישוב משתנה בהתאם למשך הזמן המבוקש ולאמצעי התחבורה שנבחר. איזוכרון של שעת נהיגה מכסה אזור גיאוגרפי ורשת כבישים גדולים משמעותית מאיזוכרון של שעת הליכה, ולכן זמן האחזור של בקשת הנהיגה ארוך יותר.
• פורמט: מכיוון שה-API משתמש ב-google.protobuf.Duration, משך הזמן צריך להיות בפורמט של מחרוזת שמסתיימת ב-"s" (לדוגמה, "3600s"), ולא מספר שלם.

נקודות מוצא והצמדה לכביש

אפשר לציין את נקודת ההתחלה של האיזוכרון בשתי דרכים:

• קואורדינטות (location): צמד של קו רוחב וקו אורך. צריך לציין גם את latitude (ב-[-90, 90]) וגם את longitude (ב-[-180, 180]). אם משמיטים אחד מהם, ה-API מתייחס אליו כאל 0.0, מה שמציב את הנקודה בקו המשווה או בקו האורך הראשי. אם משמיטים את שניהם ({}) או שולחים את (0, 0), ה-API מחזיר שגיאת 400 INVALID_ARGUMENT.
• מזהי מקומות (place): מזהה ייחודי של מקום ספציפי במפות Google. כשמציינים מזהה מקום, השירות פותר את המקום לקואורדינטת מרכז הכובד שלו ומצמיד את הנקודה הזו לכביש הקרוב ביותר. צריך להשתמש בפורמט של שם המשאב שמתחיל ב-places/ (לדוגמה, places/ChIJIQBpAG2ahYAR_6128GcTUEo). אפשר גם להשתמש במזהה מקום ללא הקידומת places/. מידע נוסף על מזהי מקומות זמין במאמר מזהי מקומות.

לא משנה מה שיטת הקלט, ה-API לא מחשב את זמני הנסיעה מהנקודה הפיזית המדויקת אם הנקודה הזו לא נמצאת בכביש, למשל בתוך פארק או בניין. כדי לטפל במצב הזה, השירות משתמש בהצמדה לכביש. התכונות של הצמדה לכביש:

• הצמדה חכמה: השירות מנסה להצמיד את נקודת המוצא לקטע הכביש הקרוב ביותר שניתן לעבור בו.
• מודעות למצב: לוגיקת ההצמדה מתחשבת בtravel_mode. אם תבקשו DRIVE או TWO_WHEELER, ה-API יתעלם משבילים להולכי רגל בלבד ויחפש את הרחוב הקרוב ביותר שמתאים לנסיעה. אם מבקשים WALK, ה-API נותן עדיפות לשבילים ולמדרכות שמתאימים להולכי רגל.
• מקרים של כשל: אם ה-API לא מוצא קטע כביש מתאים בטווח ההצמדה המקסימלי מנקודת המוצא (כ-200 מטרים, או פחות מזה ל-WALK ול-BICYCLE), ה-API מחזיר שגיאת 404 NOT_FOUND. בתכונות גיאוגרפיות גדולות (כמו פארקים, קמפוסים או נקודות תצפית), יכול להיות שמרכז הכובד של מזהה המקום יהיה רחוק יותר ממרחק ההצמדה מהכביש הקרוב ביותר שאפשר להשתמש בו במצב הנסיעה. במקרים כאלה, צריך להעביר במקום זאת את הקואורדינטות המפורשות של location בכניסה לכביש.

כיוון הנסיעה (נכנסת לעומת יוצאת)

אפשר לחשב את הנגישות הנכנסת והיוצאת באמצעות הפרמטר travelDirection (travel_direction):

• ‫FROM (יוצא): מחשב את האזור שאפשר להגיע אליו מנקודת המוצא במסגרת מגבלת הזמן שצוינה. האפשרות הזו מתאימה לתרחישי שימוש כמו אזורי החלוקה או כיסוי שירות.
• TO (נכנסת): חישוב האזור שממנו אפשר להגיע אל נקודת המוצא במסגרת מגבלת הזמן שצוינה. האפשרות הזו מתאימה לקביעת אזורי אגן ניקוז, כמו המקומות שמהם העובדים יכולים להגיע למשרד מרכזי.

מודעות לתנועה

כדי לקבוע איך נתוני התנועה ישפיעו על הפוליגון שנוצר, משתמשים בפרמטר routingPreference (routing_preference):

• ‫TRAFFIC_UNAWARE (ברירת מחדל): משתמש במגבלות המהירות של תנועה זורמת ובהיררכיית הכבישים כדי ליצור את הפוליגון של האיזוכרון. כך נוצרת צורה דטרמיניסטית שלא משתנה בהתאם לשעה ביום. הפרמטר הזה מתאים לניתוח כללי או לתכנון תרחיש בסיסי.
• ‫TRAFFIC_AWARE: חישוב איזוכרונים לפי מצב התנועה בזמן אמת, בדיוק בזמן שבו הבקשה מעובדת (בגרסה 1 אי אפשר להגדיר חותמות זמן מותאמות אישית של יציאה או הגעה בעתיד או בעבר). כתוצאה מכך, האזור הנגיש מצטמצם בשעות העומס ומתרחב בשעות השפל. בתנאים של תנועה זורמת או בשעות השפל, יכול להיות ש-TRAFFIC_AWARE ו-TRAFFIC_UNAWARE יחזירו פוליגונים כמעט זהים. הערה: מסלול מבוסס-תנועה נתמך רק כשמגדירים את travelMode לערך DRIVE או TWO_WHEELER.

החלקה ודיוק

אפשר להתאים אישית את המראה והדיוק של הפוליגונים בפלט באמצעות הפרמטרים polygonFidelity ‏ (polygon_fidelity) ו-enableSmoothing ‏(enable_smoothing). למרות שהאפשרויות האלה לא תלויות זו בזו, הן פועלות יחד כדי לקבוע את הצורה הסופית.

• ‫polygonFidelity: קובע את הרזולוציה של תאי הרשת המרחבית שמשמשת לחישוב הגבול המשוער של האזור שאפשר להגיע אליו:

  • ‫LOW: שימוש בתאי הרשת הגדולים ביותר (ברוחב של כמה מאות מטרים). האפשרות הזו מתאימה במיוחד לכיסוי אזורים גדולים עם פחות קודקודים ובלי פערים פנימיים, וכתוצאה מכך נוצרת צורה כללית שעלולה להעריך יתר על המידה את האזור הנגיש לאורך מסדרונות כבישים צרים.
  • ‫MEDIUM: איזון בין הדיוק לבין מספר הקודקודים.
  • ‫HIGH: משתמש בתאי הרשת הקטנים ביותר (ברוחב של כ-100 עד 150 מטרים). התוצאה היא התאמה הדוקה יותר לרשת הכבישים שאליה מגיעים, אבל יכולים להיווצר חורים פנימיים במקומות שבהם רשת הכבישים דלילה.
  • ‫POLYGON_FIDELITY_UNSPECIFIED: אם לא מציינים ערך, השירות בוחר את הרזולוציה באופן אוטומטי על סמך אופן הנסיעה ומשך הנסיעה. הוא משתמש בתאים קטנים יותר למשכי נסיעה קצרים ול-WALK, ובתאים גדולים יותר למשכי נסיעה ארוכים. כדי להשוות בין איזוכרונים של משכי זמן או אמצעי הגעה שונים, צריך להגדיר את polygonFidelity באופן מפורש.

    

• ‫enableSmoothing: קובע אם הקצוות המדורגים של תאי הרשת שמוגדרים לפי רמת הדיוק מעוגלים.

  • ‫false (גולמי): ברירת המחדל. הפונקציה מחזירה את הגבול המיושר לרשת. הקצוות נראים כמו מדרגות לאורך תאי הרשת. האפשרות הזו מתאימה במיוחד לדיוק אנליטי, כמו בדיקות קפדניות של נקודה בתוך מצולע.
  • ‫true (מוחלק): מעגל פינות חדות בתצוגה החזותית של המפה, תוך שמירה על השטח של כל טבעת בקירוב. הגבול כבר לא עוקב אחרי תאי הרשת.