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

ה-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 של כתובת באיכות טובה, שמחזיר 4 שדות לבקשה הספציפית הזו:

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

בקטעים הבאים מופיע סיכום של כל השדות בנכס 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.

איכות הכתובת

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

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

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

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

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

הנכס geocode

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

הנכס metadata

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

הנכס uspsData

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