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

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

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

מה אפשר לעשות

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

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

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

המאפיין verdict מחזיר את האותות הבאים של רמת פירוט:

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

האם הכתובת מלאה

התוצאה מחזירה את המאפיין addressComplete כאות לכתובת באיכות גבוהה, כלומר, אין בה רכיבים חסרים, לא פתורים או לא צפויים:

"verdict": {
    "inputGranularity": "PREMISE",
    "validationGranularity": "PREMISE",
    "geocodeGranularity": "PREMISE",
    "addressComplete": true,
    "possibleNextAction": "ACCEPT"
}

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

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

איכות הכתובת

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

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

המאפיינים 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.