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

מטרה

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

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

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

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

בדיקה

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

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

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

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

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

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

ניתוח טכני מעמיק

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

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

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

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

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

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

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

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

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

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

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