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

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

דוגמאות נפוצות: תיקון

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

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

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

החלטה לגבי עיר ומיקוד חסרים

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

{
  "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, עם כמה השמטות חשובות של נתונים, כמו יישוב ומיקוד.

חסר מספר בית

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

החלטה לגבי מספר רחוב חסר

{
    "inputGranularity": "PREMISE_PROXIMITY",
    "validationGranularity": "ROUTE",
    "geocodeGranularity": "ROUTE",
    "possibleNextAction": "FIX"
}

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

"missingComponentTypes": [
        "street_number"
      ]

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

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

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

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

החלטה לגבי מספר רחוב לא מאומת

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

{
  "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. הערך Unconfirmed מציין שהשירות לא יכול להתאים את מספר הרחוב 84 בקבוצת הנתונים שלו, והערך plausible מציין שנתוני הרכיב עדיין יכולים להיות תקינים.

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

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

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

החלטה לגבי משנה-מבנה חסר

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

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

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

"missingComponentTypes": [
        "subpremise"
      ]

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