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

מטרה

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

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

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

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

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

Address-Validation-vs-Geocoding

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

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

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

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

  • יש סיכוי גבוה לנתונים מפוקפקים, או במקרים שבהם כתובת שגויה תשפיע לרעה על התהליך. הסיבה לכך היא ש-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

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

הרחוב Fake St לא קיים ב-Mountain View, קליפורניה, והמידע הזה מופיע ב-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, ניתן להתאים את המונח 'קליפורניה' כפי שמוצג בצילום המסך בכלי הקידוד הגיאוגרפי, שאותו אפשר לנסות כאן:

alt_text

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

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

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

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

גם ה-API לאימות כתובות וגם ה-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. לכן, המערכת מחזירה את מזהה המקום (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 מציין שהתוצאה שהתקבלה לא שייכת לאף אחת מהאפשרויות שלמעלה.

אם 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 מציין שממשק ה-API לצורך גיאוקודינג לא החזיר התאמה מדויקת לבקשה המקורית, אבל הצליח להתאים חלק מהכתובת המבוקשת.

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

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

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

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

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

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

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

הסבר על תגובת ה-API לאימות כתובות

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

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

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

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

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

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

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

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

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

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

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

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

סיכום

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

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

השלבים הבאים

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

מקורות מידע נוספים:

תורמים

Google מתחזקת את המאמר הזה. הכותבים המקוריים של המאמר הם:

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

Henrik Valve | מהנדס פתרונות

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

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