בניית יכולת לאימות מיקום באמצעות הפלטפורמה של מפות Google

מטרה

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

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

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

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

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

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

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

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

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

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

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

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

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

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

1 Fake St, Mountain View, CA 94043, USA

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

הכתובת Fake St לא קיימת ב-Mountain View, קליפורניה, ו-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
     }
}

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

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

Bollschestraße 86, 12587, DE

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

ה-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) שלא קיים בבניין.

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

השטח:

"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, ולכן לא נפרט כאן.

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

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

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

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

• ‫Geocoding API - Region Biasing

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

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

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

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

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

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

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

סיכום

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

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

השלבים הבאים

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

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

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

תורמים

Google היא זו שכותבת את המאמר הזה. הוא נכתב במקור על ידי התורמים הבאים.

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

Henrik Valve | Solutions Engineer

Thomas Anglaret | מהנדס פתרונות

Sarthak Ganguly | Solutions Engineer