הסבר על תשובה בסיסית לאימות כתובת

הערה: במסמך הזה מתוארים הרכיבים הבסיסיים של תגובה לאימות כתובת של כתובת באיכות גבוהה. להנחיות לעבודה עם תרחישים של כתובות בעולם האמיתי וליצירת לוגיקה לתשובות מורכבות יותר, ראו יצירת לוגיקה לאימות.

ה-Address Validation API מספק גוף תגובה כאובייקט JSON שמכיל שני מאפיינים ברמה העליונה:

• result, אובייקט מסוג ValidationResult
• responseID

{
  "result": {
    // Validation verdict.
    "verdict": {},
    // Address details determined by the API.
    "address": {},
    // The geocode generated for the input address.
    "geocode": {},
    // Information indicating if the address is a business, residence, etc.
    "metadata": {},
    // Information about the address from the US Postal Service
    // ("US" and "PR" addresses only).
    "uspsData": {},
  },
  // A unique identifier generated for every request to the API.
  "responseId": "ID"
}

המאמר הזה מתמקד באובייקט result. מידע על השדה responseID זמין במאמר טיפול בכתובות מעודכנות.

הנכס verdict

נקודת מפתח: אפשר להשתמש בנכס verdict כדי לקבל סיכום בסיס של איכות הכתובת.

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

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

בקטעים הבאים מופיע סיכום של כל השדות בנכס verdict.

מידע נוסף זמין בקטע Verdict במדריך העזרה.

רמת הפירוט של הכתובת

רמת הפירוט של כתובת מתייחסת לרמת הפירוט שמשמש לקביעת הספציפיות של כתובת או של קוד גיאוגרפי. רמת הספציפיות של הכתובת בתגובה validationGranularity היא איתות חשוב לגבי האפשרות לשלוח חבילה לכתובת הזו.

המאפיין verdict מחזיר את אותות הפירוט הבאים:

• inputGranularity – מתאר את רמת הפירוט ששומרים מהכתובת שנשלחת ל-Address Validation API. רמת פירוט הכתובת בבקשה משפיעה על רמת פירוט הכתובת בתשובה לאימות. לדוגמה, כתובת עם inputGranularity מתחת ל-PREMISE מתחת לרמה בדרך כלל לא גורמת ל-validationGranularity ברמה PREMISE.
• validationGranularity – רמת הפירוט שבה Address Validation API יכול לאמת את הכתובת באופן מלא. ברוב המקרים, רמת פירוט של PREMISE או SUB_PREMISE מציינת כתובת איכותית שסביר להניח שאפשר לשלוח אליה.
• geocodeGranularity – תיאור של רמת הפירוט של הקוד הגיאוגרפית שמשויך לכתובת. לדוגמה, יכול להיות שברשומות של Google יצוין מספר דירה, אבל לא המיקום המדויק של הדירה הזו בתוך קומפלקס דירות גדול. במקרה כזה, הערך של validationGranularity הוא SUB_PREMISE אבל הערך של geocodeGranularityis הוא 'PREMISE'.

מידע נוסף זמין בקטע רמת פירוט במדריך העזרה.

השלמות הכתובת

התוצאה מחזירה את המאפיין addressComplete כאות לכתובת באיכות גבוהה, כלומר אין בה רכיבים חסרים, לא פתורים או לא צפויים:

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

אם הכתובת כוללת רכיבים חסרים, לא פתורים או לא צפויים, השדה מוגדר לערך false.

הערה: אם הנכס addressComplete לא מופיע בפסיקה לאחר בדיקה ידנית, הערך שלו הוא false. בהתאם לשפת התכנות שלכם, תוכלו לשלוח שאילתה לגבי התוצאה כדי לבדוק אם הנכס addressComplete קיים, או לשלוח שאילתה ישירות לגבי הנכס. דוגמה מופיעה בקטע איכות הכתובת בהמשך.

אפשר לעיין ב-addressComplete בקטע Verdict (תוצאת הבדיקה) ובקטע Address (כתובת) במדריך העזר.

איכות הכתובת

יש כמה שדות אפשריים שמציינים בעיות ברכיבי הכתובת או התאמות שלהם, כמו רכיבי כתובת חסרים או שנגזרו. לדוגמה, המאפיין verdict הבא מציין כתובת עם רכיבים לא מאומתים ושדה addressComplete חסר:

"verdict": {
    "inputGranularity": "PREMISE",
    "validationGranularity": "OTHER",
    "geocodeGranularity": "OTHER",
    "hasUnconfirmedComponents": true,
    "hasInferredComponents": true
}

מידע נוסף זמין בקטע Verdict במדריך העזרה.

המאפיינים address ו-addressComponent

נקודת מפתח: משתמשים בנכס address כדי לקבל עיצוב של כתובת. אפשר להשתמש ברכיב המשנה addressComponent כדי לחקור שגיאות ולספק מידע על השגיאות האלה ללקוחות. עם זאת, אל תבנו את השילוב כך שיסתמך על רמת האישור הספציפית של רכיבי הכתובת. איך יוצרים לוגיקה לאימות – הנחיות להטמעה.

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

מידע נוסף זמין במאמר Address במדריך העזרה.

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

מידע נוסף זמין במאמר addressComponent במדריך העזרה.

הנכס geocode

נקודת מפתח: אפשר להשתמש במאפיין geocode כדי לקבל את הקוד הגיאוגרפית או מזהה המקום, אם הלוגיקה שלכם הפעילה בעבר את Geocoding API.

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

מידע נוסף זמין במאמר Geocode במדריך העזרה.

הנכס metadata

נקודת מפתח: אפשר להשתמש במאפיין metadata כדי לקבוע את סוג הנכס שמשויך לכתובת: מגורים, תיבת דואר או עסק.

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

אפשר לעיין במאמר היקף הכיסוי של Address Validation API ובמאמר העזרה בנושא Address metadata.

הנכס uspsData

נקודת מפתח: אפשר להשתמש במאפיין uspsData כדי לקבל רמות ודאות מסירה ופרטים אחרים של USPS לגבי כתובות בארה"ב.

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

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