מדריך לפתרון לאימות כתובת

מטרה

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

אחרי שתגיעו לשלב של הערכת Address Validation API, הנה כמה הנחיות שמומלץ להשתמש בהן כחלק מהבדיקה.

מטרות הבדיקה:

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

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

הכנת הנתונים

את הבדיקה צריך לבצע על מדגם של נתוני הכתובות הקיימים. אל תבחרו נתונים ספציפיים לבדיקה, אלא דגימות אקראיות שמייצגות את האזורים הגיאוגרפיים שבהם אתם פועלים. כלומר, אם אתם פועלים גם בארצות הברית וגם בבריטניה, אבל 70% מהפעילות העסקית שלכם מתבצעת בבריטניה ו-30% בארה"ב, המדגם צריך לשקף את החלוקה הזו.

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

מכינים גודל מדגם של כ-5,000 עד 10,000 רשומות לבדיקה.

שליחת קריאה ל-API

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

אחרי שהנתונים מוכנים, צריך להריץ כל רשומת כתובת מול ה-API.

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

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

עיון בתוצאות

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

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

סקירה כללית של שדות ה-API העיקריים שמוזכרים במסמך הזה

נתוני התגובה	מה זה?	איך בודקים	איך זה עוזר?
verdict.inputGranularity	מתאר את רמת הפירוט של הכתובת שהוזנה.	SUB_PREMISE PREMISE PREMISE_PROXIMITY חסימה ROUTE OTHER	מאפשרת לקבוע אם בכתובת שהוזנה יש מספיק נתונים כדי שהיא תהיה תקינה.
verdict.validationGranularity	מתאר את אימות הפלט הכולל של הכתובת.	SUB_PREMISE PREMISE PREMISE_PROXIMITY חסימה ROUTE OTHER	מאפשר לקבוע את האיכות הכוללת של הכתובת בפלט מה-API.
verdict.hasInferredComponents	מציין אם ה-API הסיק רכיב.	True/False	ה-API יכול להוסיף רכיבים חסרים כשהוא יכול להסיק את הנתונים. לדוגמה, קוד מדינה חסר.
verdict.hasReplacedComponents	מציין אם ה-API החליף רכיב.	True/False	במקרים מסוימים, ה-API יכול להחליף רכיבים שגויים בנתונים הנכונים.
verdict.addressComplete	מציין אם הכתובת מלאה.	True/False	אם ה-API קובע שכתובת הפלט כוללת את כל הרכיבים הדרושים, הערך יהיה True.
address.missingComponentTypes	אות אזהרה אם חסרים רכיבים בכתובת.	הערכים מפורטים בטבלה 2.	להדגיש רכיבים שחסרים בכתובת חלקית.

בדיקת הכתובות התקינות

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

• ‫verdict.validationGranularity מכיל PREMISE או יותר.
• verdict.addressComplete היא true.
• אין רכיבים שהוסקו או הוחלפו.

מידע נוסף זמין בקטע אישור כתובת.

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

• האם שיעור קבלת ההזמנות מקובל?
• אם אתם משתמשים בתהליך עבודה קיים ל-Address Validation, האם שיעור הקבלה שווה או טוב יותר?

דוגמה: כתובת תקינה

הכתובת שהוזנה	אזור
76 Buckingham Palace Road, London SW1W 9TQ	בריטניה

החלטה

{
  "inputGranularity": "PREMISE",
  "validationGranularity": "PREMISE",
  "geocodeGranularity": "PREMISE",
  "addressComplete": true
}

בדיקת הכתובות הלא תקינות

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

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

• ‫verdict.validationGranularity מוגדר ל-OTHER או ל-ROUTE, בהתאם לרמת הסיכון.
• verdict.addressComplete היא false.

מידע נוסף זמין במאמר תיקון כתובת.

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

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

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

הכתובת שהזנתם	אזור
‫21 45 רחוב 40	ארה"ב

החלטה

{
  "inputGranularity": "PREMISE",
  "validationGranularity": "OTHER",
  "geocodeGranularity": "OTHER",
  "hasUnconfirmedComponents": true
}

בדיקת רכיבים חסרים או לא מאושרים

בשלב הזה, אפשר גם לבדוק רכיבים חסרים או לא מאושרים. השדה הזה הוא חלק מהאובייקט Address בתגובה. שני השדות הם missingComponentTypes ו-unconfirmedComponentTypes.

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

דוגמה: רכיב חסר ולא מאושר

הכתובת שהוזנה	אזור
Fake St, New York, NY 10011	ארה"ב

החלטה

{
     "inputGranularity": "ROUTE",
     "validationGranularity": "OTHER",
     "geocodeGranularity": "OTHER",
     "hasUnconfirmedComponents": true
}

רכיבים חסרים ורכיבים שלא אושרו

"missingComponentTypes": [
    "street_number"
],
"unconfirmedComponentTypes": [
    "route"
]

בדיקת כתובות עם תיקונים

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

האותות העיקריים שכדאי לחפש הם:

• ‫inferred,‏ replaced או spellCorrected מוגדרים כ-true באחד מ-addressComponents.
• ‫verdict.hasInferredComponents, או verdict.hasReplacedComponents מוגדר לערך true.

מידע נוסף זמין במאמר אישור כתובת.

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

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

דוגמה: כתובת עם תיקון

הכתובת שהזנתם	אזור
76 Bruckingm Palace Road, London SW1W 9TQ	בריטניה

מסלול addressComponent

{
    "componentName": {
        "text": "Buckingham Palace Road",
        "languageCode": "en"
    },
    "componentType": "route",
    "confirmationLevel": "CONFIRMED",
    "spellCorrected": true
}

[ארה"ב בלבד] בדיקת כתובת עם נתוני משנה חסרים או שגויים

‫Address Validation API יכול לזהות אם חסר חלק משני של כתובת או אם הוא שגוי, בכתובות בארה"ב.

האותות העיקריים שכדאי לחפש הם:

• באובייקט Address:
  • unconfirmedComponentTypes מכיל subpremise
  • missingComponentTypes מכיל subpremise
• באובייקט UspsData:
  • ‫dpvConfirmation הוא D (חסר מספר דירה)
  • ‫dpvConfirmation היא S (החלק בכתובת לא מאושר)

מידע נוסף זמין במאמר טיפול בכתובות בארצות הברית.

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

דוגמה: חסר מספר דירה או משרד

הכתובת שהזנתם	אזור
‎111 8th Avenue, Manhattan, NY 10011	ארה"ב

רכיב חסר

"missingComponentTypes": [
    "subpremise"
]

אישור DPV של נתוני USPS

"dpvConfirmation": "D"

[ארה"ב בלבד] בדיקת standardizedAddress של USPS

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

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

דוגמה: כתובת סטנדרטית של USPS

"standardizedAddress": {
    "firstAddressLine": "111 8TH AVE FL 11",
    "cityStateZipAddressLine": "NEW YORK NY 10011-5201",
    "city": "NEW YORK",
    "state": "NY",
    "zipCode": "10011",
    "zipCodeExtension": "5201"
}

סיכום

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

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

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

תורמים

Henrik Valve | מהנדס DevX