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

ה-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 – מתאר את רמת הפירוט שתועדה שנשלחה לממשק ה-API של אימות כתובת. רמת פירוט הכתובת משפיעה על רמת פרטי הכתובת בתגובת האימות. לדוגמה, כתובת עם inputGranularity מתחת ל-PREMISE בדרך כלל לא מסתיים ב-validationGranularity עד PREMISE ברמה.
• validationGranularity – רמת הפירוט של ה-API לאימות כתובות יכול לאמת את הכתובת באופן מלא. ברוב המקרים, רמת הפירוט של PREMISE או SUB_PREMISE מציינת כתובת לאיכות שיש סבירות גבוהה שאפשר לשלוח.
• geocodeGranularity — מתאר את רמת הפירוט של הקוד הגיאוגרפי שמשויכת לכתובת הזאת. לדוגמה, רשומות Google עשויות לציין קיים מספר דירה, אבל לא את המיקום המדויק דירה מסוימת בתוך מתחם דירות גדול. במקרה הזה, הפרמטר validationGranularity הוא SUB_PREMISE אבל geocodeGranularityisPREMISE`.

שלמות הכתובת

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

הנכס metadata

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

הנכס uspsData

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