אישור הכתובת – דוגמאות

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

דוגמאות נפוצות: אישור

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

הכתובת הוזנה אזור
Building D, 451 7th Avenue דרום, Seattle, WA 98033 ארצות הברית

קביעה לגבי נתונים שהוחלפו

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

{
  "inputGranularity": "SUB_PREMISE",
  "validationGranularity": "PREMISE_PROXIMITY",
  "geocodeGranularity": "PREMISE_PROXIMITY",
  "addressComplete": true,
  "hasUnconfirmedComponents": true
  "hasReplacedComponents": true
}

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

שאילתה לגבי מרכיבי הכתובת חושפת את התחומים הבאים:

{
  "componentName": {
    "text": "451",
  },
  "componentType": "street_number",
  "confirmationLevel": "UNCONFIRMED_BUT_PLAUSIBLE",
}
...
{
  "componentName": {
    "text": "98104",
  },
  "componentType": "postal_code",
  "confirmationLevel": "CONFIRMED",
  "replaced": true
}
...
{
  "componentName": {
    "text": "Building D",
    "language_code": "en"
  },
  "componentType": "subpremise",
  "confirmationLevel": "UNCONFIRMED_BUT_PLAUSIBLE",
}
.......

    "unconfirmedComponentTypes": [
      "street_number",
      "subpremise"
    ]

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

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

הדוגמאות הבאות ממחישות את הסוגים הבאים של מקרי קצה:

מסקנות מינוריות שמאושרות

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

  • עיר
  • ארץ
  • מיקוד
  • מדינה

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

הכתובת הוזנה אזור
1402 Allen St, MA 01118 ארצות הברית

קביעה לגבי עיר חסרה

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

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

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

{
  "componentName": {
    "text": "Springfield",
    "languageCode": "en"
  },
  "componentType": "locality",
  "confirmationLevel": "CONFIRMED",
  "inferred": true
},
{
  "componentName": {
    "text": "1806"
  },
  "componentType": "postal_code_suffix",
  "confirmationLevel": "CONFIRMED",
  "inferred": true
}

רכיב כתובת לא צפוי לא אושר

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

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

הכתובת הוזנה אזור
1 Rue Grandache, la caritat 2, 34630 Saint-Thibéry צרפת

התוצאה של רכיב הכתובת הלא צפוי לא אושרה

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

בנוסף לתוצאה עם רכיבים שלא אושרו, ה-Address Validation API מחזיר את הכתובת בפורמט הבא:

"formattedAddress": "1 Rue Grenache, 34630 Saint-Thibéry, France",

לאחר סריקה של רכיבים שלא אושרו, עולה שה-API הסיר את הערך la caritat 2 מהכתובת שהוחזרה:

{
  "componentName": {
    "text": "la caritat 2",
    "languageCode": "fr"
  },
  "componentType": "sublocality_level_1",
  "confirmationLevel": "UNCONFIRMED_BUT_PLAUSIBLE",
  "unexpected": true
}

רכיב כתובת לא צפוי שאושר

בדוגמה הזו אפשר לראות שמדובר במחוז בבריטניה, וזהו נוהל נפוץ. עם זאת, זו לא דרישה של רשות הדואר בבריטניה, ולמעשה להתעלם ממנה. למידע נוסף: postoffice.co.uk ואיך לטפל בדואר בבריטניה ובדואר בינלאומי.

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

הכתובת הוזנה אזור
33 Dunalley St, Cheltenham, Gloucestershire, GL50 4AP בריטניה

קביעה לגבי רכיב כתובת לא צפוי שאושר

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

במקרה הזה, ההערכה של address_complete היא False, וניתוח של רכיב הכתובת חושף סימון לא צפוי.

{
  "componentName": {
    "text": "Gloucestershire",
    "languageCode": "en"
  },
  "componentType": "administrative_area_level_2",
  "confirmationLevel": "CONFIRMED",
  "unexpected": true
}

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