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

מטרה

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

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

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

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

מתי בוחרים אימות כתובת לעומת Geocoding API

Address-Validation-vs-Geocoding

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

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

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

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

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

כדאי להשתמש בקידוד גיאוגרפי על פני אימות כתובת API כאשר:

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

בהמשך מפורטות כמה דוגמאות שממחישות יכולות של כתובות API לאימות כתובות בהשוואה ל-Geocoding API.

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

1 Fake St, Mountain View, CA 94043, USA

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

הכתובת Fake St לא קיימת במאונטיין ויו שבקליפורניה, וה-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 לאימות כתובות וגם ה-Geocoding API יכולים לתקן את השגיאות האלה ולהשיג את התוצאה 76 Buckingham Palace Road, London, SW1W 9TQ. עם זאת, ה-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. לכן, היא מחזירה את ה-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%. לכן אנחנו צריכים את ה-API לאימות כתובות.

אפשר להשתמש בשיטות שמתוארות למעלה כדי לשפר את רמת הדיוק של הכתובות מתגובה של Geocoding API בלבד. עם זאת, בניגוד לתוצאה של כתובת ה-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 עשוי להחזיר מיקומים של 'synthetic' כתובות שלא קיימות כמיקומים מדויקים במסד הנתונים של Google.

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

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

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

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

קיים כבר מידע שימושי שיעזור לכם להבין את התשובות שמתקבלות מה-API לאימות כתובות, ולכן לא נתמקד בו בהמשך.

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

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

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

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

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

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

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

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

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

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

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

סיכום

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

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

השלבים הבאים

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

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

תורמים

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

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

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

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

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