מדריך לאימות כתובות בכמות גדולה

מטרה

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

‫Address Validation API הוא מוצר של Google Maps Platform שמאפשר לאמת כתובת. עם זאת, הוא מעבד רק כתובת אחת בכל פעם. במאמר הזה נסביר איך להשתמש ב-High Volume Address Validation בתרחישים שונים, החל מבדיקת API ועד לאימות כתובת חד-פעמי וחוזר.

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

עכשיו נבין את תרחישי השימוש שבהם High Volume Address Validation שימושי.

בדיקה

בדרך כלל, כדי לבדוק את Address Validation API, צריך להריץ אלפי כתובות. יכול להיות שיש לכם כתובות בקובץ CSV ואתם רוצים לאמת את האיכות שלהן.

אימות חד-פעמי של כתובות

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

אימות חוזר של כתובות

יש כמה תרחישים שבהם צריך לאמת כתובות באופן קבוע:

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

מידע טכני מעמיק

למטרות המסמך הזה, אנחנו מניחים ש:

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

שמירה במטמון לשימוש בסביבת ייצור

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

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

  • נתונים מהאובייקט AddressComponent
    • confirmationLevel
    • inferred
    • spellCorrected
    • replaced
    • unexpected

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

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

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

הסבר על התשובה

אם התגובה של Address Validation API מכילה את הסמנים הבאים, אתם יכולים להיות בטוחים שהכתובת שהוזנה היא באיכות שמאפשרת מסירה:

  • הסמן addressComplete באובייקט Verdict הוא true,
  • השדה validationGranularity באובייקט Verdict הוא PREMISE או SUB_PREMISE
  • אף אחד מהרכיבים של AddressComponent לא מסומן בתור:
    • Inferred(הערה:: inferred=true יכול לקרות כש- addressComplete=true)
    • spellCorrected
    • replaced
    • ‫unexpected וגם
  • ‫confirmationLevel: רמת האישור של AddressComponent מוגדרת כ-CONFIRMED או כ-UNCONFIRMED_BUT_PLAUSIBLE.

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

  • formattedAddress
  • postalAddress
  • addressComponent componentNamesאו
  • UspsData standardizedAddress

הטמעת Address Validation ללא ממשק משתמש (headless)

על סמך הדיון שלמעלה:

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

בקטע הבא נסביר על תהליך דו-שלבי שבו אפשר לעמוד בתנאים ובהגבלות ולהטמיע Address Validation בנפח גבוה.

שלב 1:

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

תרשים א': התרשים הבא מראה איך אפשר לשפר צינור עיבוד נתונים באמצעות לוגיקה של High Volume Address Validation.

alt_text

בהתאם לתנאים ולהגבלות, אתם יכולים לשמור במטמון את הנתונים הבאים מ-addressComponent:

  • confirmationLevel
  • inferred
  • spellCorrected
  • replaced
  • unexpected

לכן, בשלב הזה של ההטמעה נשמור במטמון את השדות שצוינו למעלה ביחס ל-UserID.

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

שלב 2:

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

תרשים ב': התרשים הזה מראה איך יכול להיראות שילוב מקצה לקצה של תהליך קבלת ההסכמה מהמשתמש:

alt_text

  1. כשהמשתמש מתחבר, קודם צריך לבדוק אם שמרתם במטמון של המערכת סימוני אימות.
  2. אם יש סימונים, צריך להציג למשתמש ממשק משתמש כדי לתקן ולעדכן את הכתובת.
  3. אפשר לשלוח שוב קריאה ל-Address Validation API עם הכתובת המעודכנת או הכתובת שנשמרה במטמון, ולהציג למשתמש את הכתובת המתוקנת כדי שיאשר אותה.
  4. אם הכתובת תקינה, ה-Address Validation API מחזיר את הערך formattedAddress.
  5. אם בוצעו תיקונים, אתם יכולים להציג את הכתובת הזו למשתמש. אם לא בוצעו תיקונים, אתם יכולים פשוט לקבל את הכתובת.
  6. אחרי שהמשתמש מאשר, אפשר לשמור את ה-formattedAddress במטמון במסד הנתונים.

סיכום

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

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

השלבים הבאים

הורידו את המאמר Improve checkout, delivery, and operations with reliable addresses וצפו בוובינר Improving checkout, delivery, and operations with Address Validation .

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

תורמים

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

Henrik Valve | מהנדס פתרונות
Thomas Anglaret | מהנדס פתרונות
Sarthak Ganguly | מהנדס פתרונות