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

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

ה-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.

אפשר לעיין בתוצאה במדריך העזר.

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

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

הנכס verdict מחזיר את האותות הבאים ברמת הפירוט:

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

אפשר לעיין ברמת פירוט במדריך העזר.

סטטוס מלא של הכתובת

בתוצאה מתקבלת המאפיין 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
}

יש לעיין בתוצאה במדריך העזר.

הנכס address ו-addressComponent

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

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

ראו Address במדריך העזר.

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

ראו addressComponent במדריך העזר.

הנכס geocode

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

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

ראו Geocode במדריך העזר.

הנכס metadata

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

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

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

הנכס uspsData

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

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

כדאי לעיין בכתובות Handle United States ובחומר העזר עבור UspsData.