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

התגובה של Address Validation API מכילה את המאפיינים הבאים ברמה העליונה:

{
  // Address details determined by the API.
  "address": {},
  // Validation verdict.
  "verdict": {},
  // 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"
}

הנכס verdict

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

"verdict": {
  "inputGranularity": "PREMISE",
  "validationGranularity": "PREMISE",
  "geocodeGranularity": "PREMISE",
  "possibleNextAction": "ACCEPT",
  "addressComplete": true,
  "hasUnconfirmedComponents": false,
  "hasInferredComponents": true,
  "hasReplacedComponents": false
}

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

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

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

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

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

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

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

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

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

איכות הכתובת

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

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

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

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

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

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

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

הנכס geocode

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

הנכס metadata

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

הנכס uspsData

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