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

התשובה של 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.

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

איכות הכתובת

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

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

מה אפשר לעשות

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

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

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

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

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

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

הנכס geocode

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

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

הנכס metadata

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

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

הנכס uspsData

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

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