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