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

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

{
  "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.

מידע נוסף זמין בקטע 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.

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

איכות הכתובת

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

"verdict": {
    "inputGranularity": "PREMISE",
    "validationGranularity": "OTHER",
    "geocodeGranularity": "OTHER",
    "hasUnconfirmedComponents": true,
    "hasInferredComponents": true
}
מידע נוסף זמין בקטע Verdict במדריך העזרה.

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

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

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

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

ראו addressComponent במדריך האישי.

הנכס geocode

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

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

הנכס metadata

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

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

הנכס uspsData

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

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