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

  • יש סיכוי גבוה לנתונים מפוקפקים, או במקרים שבהם כתובת שגויה תשפיע לרעה על הצד הנגזר. הסיבה לכך היא ש-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, קליפורניה, והמידע הזה מופיע ב-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' מחזיר התאמה חלקית גם לרחוב Henry וגם לרחוב Henrietta. שימו לב: אם בקשה כוללת רכיב כתובת שכתוב בצורה שגויה, יכול להיות ש-Geocoding API יציע כתובת חלופית. הצעות שתופעלו באופן הזה לא יסומנו כהתאמה חלקית.

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

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

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

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

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

הסבר על התשובה של Address Validation API

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

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

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

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

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

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

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

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

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

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

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

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

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

סיכום

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

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

השלבים הבאים

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

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

תורמים

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

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

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

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

Sarthak Ganguly | מהנדס פתרונות