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

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

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

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

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

הנכס geocode

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

הנכס metadata

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

הנכס uspsData

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