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