דף זה תורגם על ידי Cloud Translation API.

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

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

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

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

הכתובת שהוזנה	אזור
בניין 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"
    ]

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

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

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

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

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

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

עיר
מדינה
מיקוד
מדינה

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

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

תוצאת הבדיקה לגבי עיר חסרה

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

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

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

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

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