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

מטרה

לפעמים אתם צריכים לאמת את המיקום של מקום מסוים. יש כמה שירותים שונים ב-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 API במקום ב-Address Validation API במקרים הבאים:

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

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

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

‎1 Fake St, Mountain View, CA 94043, USA

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

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

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

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

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

אם משתמשים באותה כתובת ב-Geocoding API, הוא יכול למצוא התאמה ל-"California", כמו שמוצג בצילום המסך הבא מהכלי להמרת כתובות לקואורדינטות (geocoder):

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

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

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), ולספק מטא-נתונים על הנכס, כולל העובדה שמדובר בנכס מסחרי

הנחות:

"business": true

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

"dpvConfirmation": "S"

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

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

הסבר על התגובה של Geocoding API

סקירה כללית

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

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

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

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

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 for checkout יש תיאור מפורט של ההבדלים בין כתובות תקינות לכתובות לא תקינות.

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

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

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

• Geocoding API – הטיה לפי אזור

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

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

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

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

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

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

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

סיכום

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

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

השלבים הבאים

אתם יכולים להוריד את המאמר Improve checkout, delivery, and operations with reliable addresses (שיפור התשלום, המשלוח והתפעול באמצעות כתובות מהימנות) ולצפות בוובינר Improving checkout, delivery, and operations with Address Validation (שיפור התשלום, המשלוח והתפעול באמצעות Address Validation).

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

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

תורמים

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

מחברים ראשיים:

Henrik Valve | Solutions Engineer

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

Sarthak Ganguly | Solutions Engineer