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

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

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

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

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

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

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

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

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

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

האותות האלה מצביעים על כתובת שלא ניתן לשלוח אליה הודעות, לכן אפשר להריץ שאילתה על 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"
}

הערך של 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
}

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

}

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

"missingComponentTypes": [
        "subpremise"
      ]

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