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