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

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

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

פרטים נוספים מופיעים בקטעים addressComplete בקטע Verdict ו-כתובת במדריך.

איכות הכתובת

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

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

פרטים נוספים זמינים בקטע קביעת ערכים במדריך העזר.

הנכסים address ו-addressComponent

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

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

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

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

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

הנכס geocode

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

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

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

הנכס metadata

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

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

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

הנכס uspsData

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

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

פרטים נוספים זמינים בקטע טיפול בכתובות בארצות הברית ובחומר העזר של UspsData.