שיטות מומלצות לשימוש ב-Isochrones API

החלקה ודיוק

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

  • ‫polygonFidelity (polygon_fidelity): רזולוציה. ההגדרה קובעת את הגודל של תאי הרשת המרחבית הבסיסית שמשמשים לחישוב האזור שאפשר להגיע אליו.

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

    גודלי התאים הם משוערים. יכול להיות שאיזוכרונים גדולים מאוד יכללו הכללה נוספת כדי לשמור על גודל תגובה שניתן לניהול.

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

איך הם פועלים ביחד: רמת הפירוט קובעת את רמת הפירוט הבסיסית שעליה פועל אלגוריתם ההחלקה.

  • רמת דיוק גבוהה + החלקה: יוצרת צורה מפורטת במראה אורגני שעוקבת מקרוב אחרי סיומות של כבישים.
  • רמת דיוק נמוכה + החלקה: יוצרת צורה רחבה וכללית של "כתם".

גודל המטען הייעודי (payload) ועיבוד (rendering)

איזוכרונים גדולים (במיוחד בקשות ארוכות עם רמת דיוק של HIGH) יכולים להכיל עשרות אלפי קואורדינטות, והתגובה בפורמט JSON לא דחוס יכולה להיות בגודל של כמה מאות קילובייט או יותר.

  • רוחב פס: שימו לב שגודל התגובה ב-JSON הוא משמעותי לבקשות עם משך זמן מקסימלי ורמת דיוק גבוהה.
  • עיבוד: עיבוד של מצולעים מפורטים מאוד משפיע על הביצועים בצד הלקוח. כדי להקטין את מספר הקודקודים ואת גודל המטען הייעודי (payload), בוחרים באפשרות polygonFidelity: MEDIUM או LOW, או מפשטים את הגיאומטריה בצד הלקוח לפני הרינדור באמצעות אלגוריתם לפישוט קווים כמו Douglas-Peucker.

זמן אחזור וזמן קצוב לתפוגה של לקוח

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

  • זמן קצוב מומלץ לתפוגה של לקוח: מגדירים את המועדים האחרונים של לקוח HTTP או gRPC ל30 שניות לפחות, כדי שבקשות ארוכות לא יבוטלו מוקדם מדי בגלל זמן קצוב קצר לתפוגה של לקוח.

טיפול בשגיאות

הטמיעו לוגיקה של ניסיון חוזר עם השהיה מעריכית לפני ניסיון חוזר (exponential backoff) ורעידות (jitter) לתגובות של הגבלת קצב של יצירת בקשות עם קוד 429 RESOURCE_EXHAUSTED ושגיאות בחיבור לשרת עם קוד 5xx. אל תנסו שוב לשלוח בקשות שקיבלו שגיאות לקוח מסוג 400,‏ 403 או 404 בלי לשנות את הבקשה:

  • ‫INVALID_ARGUMENT (400): צריך לוודא שהערך של travelDuration הוא בין 1s ל-3600s (DRIVE/TWO_WHEELER) או 7200s (WALK/BICYCLE), שהערך של location לא הושמט והוא לא (0, 0) (או שהערך של place הוא מזהה מקום חוקי), ושהערך של TRAFFIC_AWARE משמש רק עם DRIVE או TWO_WHEELER. אם משמיטים את latitude או את longitude, המערכת מתייחסת לערך שהושמט כ-0.0, כך שהשמטה של אחד מהם בדרך כלל לא גורמת לשגיאת 400 (אלא אם גם הערך השני הוא 0.0). אם האיזוכרון מופיע במקום הלא נכון, צריך לבדוק שוב את שני הערכים.
  • ‫PERMISSION_DENIED (403): מוודאים שמפתח ה-API או אסימון ה-OAuth כלולים, ושה-Isochrones API והחיוב מופעלים בפרויקט ב-Google Cloud.
  • ‫NOT_FOUND (404): לא ניתן היה לזהות את המיקום של place, או שלא ניתן היה להצמיד את נקודת המוצא לכביש סמוך שמתאים לאמצעי התחבורה (במרחק של כ-200 מטרים, או פחות במקרה של WALK ו-BICYCLE).
  • RESOURCE_EXHAUSTED (429): הפרויקט חרג ממכסת הבקשות לדקה (ברירת המחדל היא 300 בקשות לדקה). נסו שוב עם השהיה מעריכית לפני ניסיון חוזר (exponential backoff).