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

‫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,
  "possibleNextAction": "ACCEPT"
}

בקטעים הבאים מופיע סיכום של כל השדות בנכס verdict.

לפרטים נוספים, אפשר לעיין בVerdict במדריך העזר.

הפעולה הבאה האפשרית

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

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

גרנולריות של כתובת מתייחסת לרמת הפירוט שמשמשת לקביעת הספציפיות של כתובת או של קואורדינטות גיאוגרפיות. רמת הפירוט של הכתובת בתגובה 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,
    "possibleNextAction": "ACCEPT"
}

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

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

איכות הכתובת

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

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

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

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

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

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

מידע נוסף זמין במדריך addressComponent.

הנכס geocode

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

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

הנכס metadata

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

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

הנכס uspsData

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

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