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

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

הנכס geocode

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

הנכס metadata

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

הנכס uspsData

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