תיקון כתובת – דוגמאות

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

דוגמאות נפוצות: fix

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

חסר שם עיר ומיקוד

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

הכתובת שהוזנה אזור
21 45 40th street ארה"ב

תוצאה של עיר ומיקוד חסרים

הדוגמה הבאה מדגישה את האותות החשובים מהתגובה.

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

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

{
  "componentName": {
    "text": "21",
    "languageCode": "en"
  },
  "componentType": "street_number",
  "confirmationLevel": "UNCONFIRMED_BUT_PLAUSIBLE"
},
{
  "componentName": {
    "text": "45 40th street",
    "languageCode": "en"
  },
  "componentType": "route",
  "confirmationLevel": "UNCONFIRMED_BUT_PLAUSIBLE"
},
{
  "componentName": {
    "text": "United States",
    "languageCode": "en"
  },
  "componentType": "country",
  "confirmationLevel": "CONFIRMED"
}

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

חסר מספר בית

בדוגמה הזו חסר מספר בית.

הכתובת שהוזנה אזור
Buckingham Palace Road, ‏ SW1W 9TQ London בריטניה
תוצאה של מספר בית חסר
{
    "inputGranularity": "PREMISE_PROXIMITY",
    "validationGranularity": "ROUTE",
    "geocodeGranularity": "ROUTE",
    "possibleNextAction": "FIX"
}

שוב, השדה possibleNextAction מספק אינדיקציה ראשונית לכך שאולי לא ניתן לשלוח אל הכתובת. בנוסף, הערך של validationGranularity הוא ROUTE, שמציין התאמה לרחוב, אבל אין מספיק מידע כדי להגיע לנכס. בנוסף, המאפיין addressComplete חסר בפסיקה, ולכן הערך שלו הוא false. שאילתה נוספת על האובייקט address חושפת סוג רכיב חסר:

"missingComponentTypes": [
        "street_number"
      ]

דוגמאות למקרים קיצוניים: תיקון

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

מספר הרחוב לא אומת

בתרחיש הזה, Address Validation API לא יכול לאשר את מספר הרחוב שצוין, אבל הוא מציין שהכתובת מלאה.

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

התוצאה של בדיקת מספר הרחוב שלא אומת

בדוגמה הבאה מודגשים האותות החשובים.

{
  "inputGranularity": "PREMISE",
  "validationGranularity": "PREMISE_PROXIMITY",
  "geocodeGranularity": "PREMISE_PROXIMITY",
  "addressComplete" : true,
  "hasUnconfirmedComponents": true,
  "possibleNextAction": "ACCEPT"
}

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

{
  "componentName": {
    "text": "84",
    "languageCode": "en"
  },
  "componentType": "street_number",
  "confirmationLevel": "UNCONFIRMED_BUT_PLAUSIBLE"
}

כאן, השדה confirmation_level של street_number מוגדר להיות UNCONFIRMED_BUT_PLAUSIBLE. לא מאומת: השירות לא יכול להתאים את מספר הרחוב 84 במערך הנתונים שלו, וסביר: ייתכן שנתוני הרכיב עדיין תקפים.

חסר נכס משנה

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

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

הכתובת שהוזנה אזור
1 Doctor Carlton B Goodlett Place, San Francisco, CA 94102 ארה"ב

תוצאה של כתובת משנה חסרה

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

{
  "inputGranularity": "PREMISE",
  "validationGranularity": "PREMISE",
  "geocodeGranularity": "PREMISE",
  "hasInferredComponents": true,
  "possibleNextAction": "CONFIRM_ADD_SUBPREMISES"
}

שאילתה מסוג address חושפת את הפרטים הבאים:

"missingComponentTypes": [
        "subpremise"
      ]

לאחר בדיקה נוספת, נתוני USPS כוללים קוד dpvConfirmation‏D, שמציין גם כן שחסרה יחידה משנה.