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

מטרה

לפעמים יש צורך לאמת את המיקום של מקום מסוים. יש כמה שירותים שונים ב-Google Maps Platform שיכולים לעזור לכם בתרחיש לדוגמה הזה. במאמר הזה אנחנו עוזרים לכם לבחור בין שני שירותי האימות העיקריים של מיקומים – Address Validation API ו-Geocoding API.

‫Address Validation API הוא מוצר של Google Maps Platform שעוזר ללקוחות לאמת אם כתובת מסוימת מדויקת או לא.

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

כאן אפשר למצוא סקירה כללית ברמה גבוהה של ההבדלים בין Address Validation API לבין Geocoding API.

נסו זאת בעצמכם: היכנסו למסוף Google Cloud והפעילו את Address Validation API ואת Places API.

מתי כדאי לבחור ב-Address Validation API ומתי ב-Geocoding API

הערות לגבי תרשים הזרימה שלמעלה:

• תרחיש שימוש של אינטראקציית משתמש מתייחס למצב שבו המשתמש נוכח כדי לבצע אינטראקציה עם התוצאות.
• ‫השלמה אוטומטית למקומות הוא ממשק API של JavaScript, ולכן הוא מתאים לשילוב עם ממשקי משתמש.
• יכול להיות שאתם מודעים לבעיות באיכות הנתונים בכתובות הקיימות שלכם. לכן, גם אם אתם רוצים רק קואורדינטות, מומלץ להריץ את המיקומים האלה דרך Address Validation API כדי לתקן את מערכי הנתונים.

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

כדאי להשתמש ב-Address Validation API במקום ב-Geocoding API במקרים הבאים:

• יש סיכוי גבוה לנתונים מפוקפקים, או במקרים שבהם קבלת כתובת שגויה תשפיע לרעה על תהליכים בהמשך. הסיבה לכך היא ש-Address Validation API מספק יותר משוב על הסיבה לכך שקלט לא קיבל תוצאה ברמת דיוק גבוהה.
• אתם צריכים לתקן את הקלט של המשתמשים (למשל, שגיאות כתיב או שדות חסרים), כדי להגדיל את הסיכוי לקבל תוצאה מדויקת בפלט.
• האזור הגיאוגרפי שלכם מחזיר יותר מטא-נתונים מ-Address Validation API בהשוואה ל-Geocoding API, כמו סיווג של סוג הבניין למגורים או למסחר.

כדאי להשתמש ב-Geocoding במקום ב-Address Validation API במקרים הבאים:

• המטרה העיקרית שלך היא לאחזר את המיקום של כתובת, ורמת הדיוק של כתובות ספציפיות לא בהכרח קריטית.
  • לדוגמה, יכול להיות שתרצו ליצור מפת חום מקבוצת נתונים גדולה.
• אתם צריכים פרטי יעד מקומיים מאוד, כמו כניסות לבניינים, קווי מתאר של בניינים או נקודות ניווט לאיסוף ולהורדה (זמינים ב-Geocoding API בגרסה 4 באמצעות השיטה SearchDestinations).
• אתם צריכים פתרון גלובלי ו-Address Validation API לא זמין בכל אזורי היעד.

הנה כמה דוגמאות שממחישות את היכולות של Address Validation API בהשוואה ל-Geocoding API.

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

1 Fake St, Mountain View, CA 94043, USA

‫Address Validation API מפרק את הקלט הזה לרכיבי הכתובת הנפרדים (רחוב, עיר, מדינה וכו'). הוא יכול גם לספק משוב מפורט לגבי הסיבה לכך שהכתובת לא תקינה, עד לרמה של PREMISE.

הכתובת Fake St לא קיימת ב-Mountain View, קליפורניה, ו-Address Validation API משקף זאת בפרטים ברמת הרכיב שמוחזרים:

{
  "componentName": {
    "text": "Fake St",
    "languageCode": "en"
   },
   "componentType": "route",
   "confirmationLevel":"UNCONFIRMED_BUT_PLAUSIBLE"
 }

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

אם נשתמש בתוצאת ה-API כמשוב, נוכל להסיק שרכיב הרחוב של הקלט הזה (Fake St) הוא הבעייתי.

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

עם זאת, התוצאה היא קואורדינטות של המדינה כולה, עם מינימום משוב לגבי הרכיבים בקלט שאולי היו פגומים.

דוגמה לשגיאת איות

76 Buckingamm Palace Road, Londn, SW1W 9TQ, GB

בכתובת שלמעלה יש כמה שגיאות איות, אחת בשם הרחוב והשנייה בשם היישוב.

גם Address Validation API וגם Geocoding API יכולים לתקן את השגיאות האלה ולהחזיר את התוצאה 76 Buckingham Palace Road, London, SW1W 9TQ. עם זאת, ה-Address Validation API יכול לספק מידע נוסף על התהליך.

הנה דוגמה לאחד מרכיבי הכתובת שהוזן עם שגיאת כתיב:

{
  "componentName": {
    "text": "Buckingham Palace Road",
    "languageCode": "en"
        },
        "componentType": "route",
        "confirmationLevel": "CONFIRMED",
        "spellCorrected": true
     }
}

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

דוגמה לנתונים חסרים ולשגיאת כתיב

Bollschestraße 86, 12587, DE

בכתובת שלמעלה יש שגיאת איות בשם הרחוב, וחסרה העיר (היישוב) ברלין.

ה-Address Validation API יכול לתקן את שתי השגיאות האלה ולהחזיר קואורדינטות גיאוגרפיות ברמה PREMISE וכתובת שאומתה ברמה PREMISE:

Bölschestraße 86, 12587 Berlin, DE

במקרה הזה, Geocoding API לא מצליח להתגבר על שגיאות הקלט, ומחזיר את התוצאה ZERO_RESULTS.

דוגמה למטא-נתונים נוספים של כתובת

‎111 8th Avenue Ste 123, New York, NY 10011-5201, US

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

‫Address Validation API יכול לאמת את הכתובת עד לרמת PREMISE (111 8th Ave), ולספק מטא-נתונים על הנכס, כולל העובדה שמדובר בנכס מסחרי

premises:

"business": true

בנוסף, הערך של dpvConfirmation שמוחזר כחלק מ-uspsData בתגובה הוא S:

"dpvConfirmation": "S"

ערך dpvConfirmation של S מציין שהכתובת אומתה ברמה PREMISE, אבל מספר היחידה שצוין בקלט לא משויך לכתובת הזו.

‫Geocoding API לא יכול לספק את המידע הזה.

הסבר על התגובה מה-Geocoding API

סקירה כללית

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

ה-Geocoding API פועל על ידי פתרון של רכיבי כתובת בהיררכיה.

לדוגמה, **123 Example Street, Chicago, 60007, USA נפתר בסדר הבא:

/ Example Street/ Chicago/ 60007/ USA ייבדקו לפי הסדר הזה. ההתאמה הראשונה במקרה הזה היא שיקגו, ובאופן ספציפי יותר, 60007מיקוד. לכן, היא מחזירה את מזהה המקום הבא עבור המיקוד הזה:

ChIJwRKzf8ixD4gRHiXqucwr_HQ

התשובה של Geocode API כוללת את המידע הבא:

        "partial_match": true,
           "place_id": "ChIJwRKzf8ixD4gRHiXqucwr_HQ",
           "types": [
               "postal_code"
           ]

‫Geocoding API יכול לאשר לאיזה סוג מקום הכתובת הזו שייכת. כאן אפשר למצוא רשימה של types הכתובות שמוחזרות על ידי Geocoding API.

אם אף אחד מהרכיבים של הקלט לא נפתר, ה-API מחזיר:

{
   "results": [],
   "status": "ZERO_RESULTS"
}

אם שולחים בקשה עם שם הרחוב בלבד, בלי מספר הבית, התוצאה שמתקבלת היא בפורמט הבא:

"types": [
  "route"
]

כלומר, Geocoding API לא הצליח למצוא או להתאים מספר רחוב.

הערה: כדי לדעת אם כתובת קיימת, צריך לבדוק אם אחד מהפרמטרים (כמו types, partial_match, results, status)) מוגדר בתגובה של Geocoding API. כך תגדל בהדרגה רמת הוודאות שכתובת מסוימת קיימת, אבל היא לא תהיה מדויקת ב-100%. לכן אנחנו צריכים את Address Validation API.

אתם יכולים להשתמש בשיטות שלמעלה כדי להגביר את רמת הוודאות לגבי הדיוק של הכתובת, רק על סמך התגובה מה-Geocoding API. עם זאת, בניגוד לתוצאה של Address Validation API, ‏Geocoding API לא יחזיר משוב מדויק כדי לקבוע את דיוק התוצאה.

סוג המיקום

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

• ROOFTOP מציין שהתוצאה שהוחזרה היא קואורדינטה מדויקת, שיש לנו לגביה נתוני מיקום מדויקים עד לרמת הכתובת.
• ‫RANGE_INTERPOLATED מציין שהתוצאה שהוחזרה משקפת קירוב (בדרך כלל בכביש) שחושב על ידי אינטרפולציה בין שתי נקודות מדויקות (כמו צמתים). תוצאות משוערות מוחזרות בדרך כלל כשאין קודי מיקום של גגות עבור כתובת רחוב.
• ‫GEOMETRIC_CENTER מציין שהתוצאה שהוחזרה היא המרכז הגיאומטרי של תוצאה כמו קו פוליגוני (לדוגמה, רחוב) או פוליגון (אזור).
• APPROXIMATE מציין שהתוצאה שהתקבלה לא מתאימה לאף אחת מהאפשרויות שלמעלה.

אם Geocoding API מחזיר location_type של ROOFTOP או RANGE_INTERPOLATED, זה לא בהכרח אומר שהכתובת קיימת. באופן דומה, אם Geocoding API מחזיר את הדגל partial_match כשהוא מוגדר ל-true, יכול להיות שזו עדיין התוצאה הנכונה בשבילכם.

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

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

התאמה חלקית והתאמה שגויה

אם הכתובת היא התאמה חלקית, כלומר Geocoding API לא הצליח לזהות את הכתובת המדויקת, התגובה תכיל את הפרטים הבאים:

"partial_match": true,
"types": [
           "locality",
           "political"
         ]

חשוב עוד יותר מסוגי המיקומים שלמעלה, לשקול מתי partial_match = true נמצא בתשובה. ‫partial_match מציין ש-Geocoding API לא החזיר התאמה מדויקת לבקשה המקורית, אבל הצליח להתאים חלק מהכתובת המבוקשת.

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

לדוגמה, המחרוזת '21 Henr St, Bristol, UK' תחזיר התאמה חלקית גם ל-Henry Street וגם ל-Henrietta Street. שימו לב שאם בקשה כוללת רכיב כתובת עם שגיאת כתיב, יכול להיות שה-Geocoding API יציע כתובת חלופית. הצעות שמופעלות בדרך הזו לא יסומנו כהתאמה חלקית.

כתובות סינתטיות

יכול להיות ש-Geocoding API יחזיר מיקומים לכתובות 'סינתטיות' שלא קיימות כמיקומים מדויקים במסד הנתונים של Google.

בתרחישים כאלה, אובייקט התגובה מכיל בדרך כלל מזהה מקום ארוך ואת המאפיין הבא: geometry.location_type=APPROXIMATE.

אם אתם נתקלים במדדים האלה בתשובה, כדאי לסמן את כתובת הקלט כלא תקינה ולנסות לאמת אותה באמצעי אחר.

הערה: זהו עוד מקרה שבו אפשר לקבל משוב ישיר אם כתובת לא קיימת באמצעות Address Validation API.

הסבר על התגובה מה-Address Validation API

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

• כאן אפשר למצוא סקירה כללית של אובייקט התגובה.
• כאן אפשר לראות הדגמה של הרכיבים השונים בתשובה
• במסמך בנושא אימות כתובות בקופה יש תיאור מפורט של ההבדלים בין כתובות תקינות לכתובות לא תקינות.

שיטות מומלצות

ציון מיקום גיאוגרפי

כשמבצעים קריאות ל-Address Validation API או ל-Geocoding API, מומלץ לנסות להגביל את האזור הגיאוגרפי שבו מחפשים את הכתובת. שני ממשקי ה-API מטמיעים את זה בשתי דרכים שונות:

• ‫Geocoding API - Region Biasing

  אם אתם יודעים שהקואורדינטות יהיו במדינה מסוימת, תוכלו לקבל תוצאות הרבה יותר טובות באמצעות הטיה לפי אזור. לדוגמה, אם אתם מבצעים המרת כתובות לקואורדינטות בקנדה, מומלץ להוסיף &region=ca לבקשות כדי להטות את התוצאות לקנדה. חשוב לזכור שהטיה לפי אזור רק מעדיפה תוצאות באזור הזה. עדיין יכול להיות שתקבלו תוצאות מחוץ לאזור.

• Address Validation API – קוד אזור

  באופן דומה, Address Validation API מפיק תוצאות מדויקות יותר אם מעבירים בבקשה קוד ISO2 באמצעות השדה regionCode.

אחסון מזהי מקומות

כדי לשמור מידע מפלטפורמת מפות Google על המיקום לבקשות עתידיות, אפשר לשמור את מזהה המקום ללא הגבלת זמן במסד הנתונים שלכם כמאפיין של המיקום. צריך לשלוח בקשת Find Place רק פעם אחת לכל placeID. אפשר גם לחפש את מזהה המקום בכל פעם שמשתמש מבקש פרטי עסקה.

כדי לוודא שתמיד יהיה לכם את המידע הכי עדכני, רעננו את מזהי המקומות כל 12 חודשים באמצעות בקשה לפרטי מקום עם הפרמטר place_id.

הערה: מומלץ לעיין גם במדריך לשיטות מומלצות להמרת כתובות לקואורדינטות (geocoding).

סיכום

במסמך הזה מתוארים ההבדלים העיקריים בין Address Validation API לבין Geocoding API. לסיכום, כדאי להשתמש ב-Address Validation API במקרים הבאים:

• חשוב להזין כתובת מדויקת למשלוח דואר, במיוחד כדי שהדואר יגיע ליעד.
• נתוני הקלט ידועים כנתונים באיכות נמוכה. ה-API של אימות כתובות סלחני יותר לשגיאות בקלט, יסמן רכיבי כתובת שלא ניתן לאמת ויבצע תיקונים בנתוני הקלט.
• נדרש מידע נוסף על הכתובת, כמו מגורים לעומת מסחר (זמין באזורים נבחרים).

השלבים הבאים

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

הצעות לקריאה נוספת:

• Address Validation בתהליך התשלום במסחר אלקטרוני
• מאמרי עזרה בנושא השלמה אוטומטית למקומות
• מאמרי העזרה של Address Validation API
• דוחות ב-Google Maps Platform

תורמים

‫Google מתחזקת את המאמר הזה. הכותבים הבאים כתבו אותו במקור.

המחברים העיקריים:

Henrik Valve | Solutions Engineer

תומאס אנגלרט | מהנדס פתרונות

Sarthak Ganguly | Solutions Engineer