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

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

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

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

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

הוזנה כתובת	אזור
‪Building D, 451 7th Avenue South, Seattle, WA 98033	ארה"ב

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

בדוגמה שלמטה מודגשים האותות החשובים מתוך הפסיקה.

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

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

שאילתה של רכיבי הכתובת חושפת את הבעיות הבאות:

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

טיפ: כדי לראות את התגובה לכתובת המקורית, אפשר לבדוק את הכתובת הנכונה בהדגמה באמצעות 451 7th Avenue South, Kirkland, WA 98033.

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

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

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

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

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

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

• עיר
• מדינה (State)
• מיקוד
• מדינה

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

הוזנה כתובת	אזור
‪1402 Allen St, MA 01118	ארה"ב

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

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

במצבים שבהם Address Validation 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 Grenache, 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
}

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

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

בדוגמה הזו רואים שכתובת שסופקה כוללת מחוז בבריטניה, וזהו נוהג נפוץ. עם זאת, זו לא דרישה של רשות הדואר בבריטניה, והמערכת מתעלמת מהתג הזה. אפשר לעיין בכתובות postoffice.co.uk ובמאמר How to address UK and international mail.

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

הוזנה כתובת	אזור
‪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 גם בודק את המידע כדי לוודא שהוא בפורמט הנכון.

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