המרת כתובות לקואורדינטות בדיוק משופר

מפתחים באזור הכלכלי האירופי (EEA)

השיטות GeocodeAddress ו-SearchDestinations תומכות בפרמטר האופציונלי effort, שמאפשר לכם לשלוט בפשרה בין זמן האחזור של התגובה לבין הדיוק של פתרון הכתובת.

המרת כתובות רגילה לקואורדינטות מטפלת בכתובות דואר בפורמט תקין בזמן אחזור של פחות משנייה, אבל קלט בעולם האמיתי הוא בדרך כלל חלקי, לא רשמי או מורכב (לדוגמה, "Flat 4B, Sunrise Apartments, opposite Central Mall, Andheri West, Mumbai" או "where the warriors play, sf"). אם מגדירים רמת effort גבוהה יותר, אפשר להורות ל-Geocoding API להחיל הסקת מסקנות מורחבת והפגת עמימות כדי לפתור כתובות בעייתיות.

רמות המאמץ

צריך לציין אחד מהערכים הבאים בפרמטר effort:

רמת המאמץ תיאור זמן אחזור אופייני תרחישים מומלצים לדוגמה
EFFORT_UNSPECIFIED ערך ברירת המחדל. ההתנהגות זהה לזו של המאמץ LOW. פחות משנייה המרת כתובות רגילה לקואורדינטות כברירת מחדל.
LOW אופטימיזציה לזמני התגובה המהירים ביותר. לא מבצע חיפוש מורחב או הפגת עמימות של כתובות מורכבות. פחות משנייה חיפוש אינטראקטיבי בזמן אמת, אימות כתובות רגילות בנפח גבוה.
MEDIUM איזון בין מהירות לדיוק. רוב הבקשות מוחזרות עם זמן אחזור נמוך רגיל. אם הכתובת לא ברורה או קשה לזיהוי, השירות מבצע עיבוד נוסף כדי לשפר את הדיוק, וזה יכול לקחת כמה שניות. פחות משנייה לכתובות רגילות; עד כמה שניות (≤ 4 שניות) לכתובות לא ברורות תהליכי עבודה אינטראקטיביים של משתמשים (כמו אישור כתובת בתשלום בקופה) שבהם המשתמשים יכולים להמתין זמן קצר.
HIGH ממקסם את הדיוק של זיהוי הכתובות במקרה של כתובות חלקיות, לא רשמיות או מורכבות. זמני התגובה עשויים להיות ארוכים משמעותית. עד 20 שניות לכתובות מורכבות עיבוד ברקע, גיאוקוד של קבוצת נתונים, שיגור לוגיסטי או שיפור אסינכרוני של כתובת אחרי התשלום.

דוגמאות לבקשות

חיפוש יעדים (SearchDestinations)

כוללים את השדה effort בגוף בקשת ה-JSON של בקשת ה-POST אל https://geocode.googleapis.com/v4alpha/geocode/destinations. הפרמטר effort משפיע בעיקר על הרזולוציה של addressQuery:

curl -X POST -d '{
  "addressQuery": {
    "addressQuery": "Flat 4B, Sunrise Apartments, opposite Central Mall, Andheri West, Mumbai"
  },
  "effort": "HIGH"
}' \
-H 'Content-Type: application/json' \
-H "X-Goog-Api-Key: API_KEY" \
-H "X-Goog-FieldMask: *" \
https://geocode.googleapis.com/v4alpha/geocode/destinations

המרת כתובת לקואורדינטות (GeocodeAddress)

מעבירים את הפרמטר effort כפרמטר של שאילתת URL בבקשת GET לנקודת הקצה (endpoint) של /v4alpha/:

curl -X GET -H 'Content-Type: application/json' \
-H "X-Goog-Api-Key: API_KEY" \
"https://geocode.googleapis.com/v4alpha/geocode/address/where+the+warriors+play,+sf?effort=MEDIUM"

הפחתת ההשפעה של זמן האחזור

כשמשתמשים במאמץ MEDIUM או HIGH באפליקציה, שליחת בקשה במעבר יחיד היא השילוב הפשוט ביותר, אבל בקשות במצבים האלה יכולות לגרום לזמן אחזור ארוך יותר, שעלול לעכב תהליכי עבודה סינכרוניים, שגלויים למשתמשים ורגישים לזמן אחזור.

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

  1. שלב 1 (אינטראקטיבי): שולחים בקשה סינכרונית עם effort=LOW (או ברירת המחדל) כדי לאמת את הכתובת באופן מיידי עם זמן אחזור של פחות משנייה.
  2. שלב 2 (ברקע): שולחים בקשת מעקב אסינכרונית עם effort=MEDIUM או effort=HIGH (לדוגמה, אחרי התשלום או לפני השליחה) כדי לפתור כתובות מורכבות ולהמיר אותן לקואורדינטות, כניסות ונקודות ניווט ברמת דיוק גבוהה בלי לחסום את המשתמש.

מכסות שימוש

בשלב ההשקה הניסיוני (v4alpha), בקשות שבהן הערך של effort מוגדר כ-MEDIUM או כ-HIGH כפופות למגבלות קצב מחמירות יותר מאשר בקשות רגילות (LOW). אם האפליקציה חורגת מהמגבלות האלה, ה-API מחזיר את השגיאה RESOURCE_EXHAUSTED (HTTP 429). אם נתקלתם בשגיאות HTTP 429 או שאתם צריכים מכסה גדולה יותר לתרחיש לדוגמה שלכם, אתם יכולים לפנות אלינו דרך ערוץ המשוב.

משוב

זו תכונה ניסיונית של Geocoding API. נשמח לקבל משוב בכתובת geocoding-feedback-channel@google.com.