ה-API לאימות כתובת מספק גוף תשובה כקובץ JSON אובייקט שמכיל שני מאפיינים ברמה העליונה:
result
, אובייקט מסוגValidationResult
responseID
{
"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
}
בקטעים הבאים מופיע סיכום של כל השדות בנכס verdict
.
צפייה קביעה במדריך העזר. |
רמת פירוט הכתובת
רמת הפירוט של הכתובת מתייחסת לרמת הפירוט שמשמשת לקביעת
ספציפיות של כתובת או קואורדינטות. רמת הספציפיות של הכתובת בתגובה validationGranularity
היא איתות חשוב לגבי האפשרות לשלוח חבילה לכתובת הזו.
המאפיין verdict
מחזיר את אותות הפירוט הבאים:
inputGranularity
– מתאר את רמת הפירוט שתועדה שנשלחה לממשק ה-API של אימות כתובת. רמת פירוט הכתובת משפיעה על רמת פרטי הכתובת בתגובת האימות. לדוגמה, כתובת עםinputGranularity
מתחת ל-PREMISE
בדרך כלל לא מסתיים ב-validationGranularity
עדPREMISE
ברמה.validationGranularity
– רמת הפירוט שבה Address Validation API יכול לאמת את הכתובת באופן מלא. ברוב המקרים, רמת הפירוט שלPREMISE
אוSUB_PREMISE
מציינת כתובת לאיכות שיש סבירות גבוהה שאפשר לשלוח.geocodeGranularity
— מתאר את רמת הפירוט של הקוד הגיאוגרפי שמשויכת לכתובת הזאת. לדוגמה, רשומות Google עשויות לציין קיים מספר דירה, אבל לא את המיקום המדויק דירה מסוימת בתוך מתחם דירות גדול. במקרה כזה, הערך שלvalidationGranularity
הואSUB_PREMISE
, אבל הערך שלgeocodeGranularity
is
הוא '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
}
פרטים נוספים זמינים בקטע קביעת ערכים במדריך העזר. |
הנכסים address
ו-addressComponent
בנכס address
יש עיצוב לכתובת המעובדת שצוינה
הבקשה, יחד עם סיכומים ברמת הרכיבים של הכתובת, כולל
חלקים שגויים של הכתובת, החליפו חלקים שגויים והסקת מסקנות
חלקים.
מידע נוסף זמין במאמר Address במדריך העזרה. |
המאפיין addressComponent
הוא רכיב משנה של address
שמספק
רשימה מפורטת של הרכיבים או הרכיבים של הכתובת
הסתיים העיבוד של ה-API לאימות כתובת. ה-API מזהה כל רכיב
מצוין לפי השם, הסוג ורמת האישור שלו.
מידע נוסף זמין במאמר addressComponent במדריך העזרה. |
הנכס geocode
המאפיין geocode
מציין את המיקום המקודד שמשוייך לכתובת שהוזנה. הנכס הזה מספק פרטים על המיקום עצמו, כמו
מזהה המקום.
מידע נוסף זמין במאמר Geocode במדריך העזרה. |
הנכס metadata
ייתכן שהנכס הזה לא יאוכלס לכל כתובת שמעובדת ממשק API לאימות כתובת, אבל מציין אם הכתובת היא מסוג 'מגורים' עסק או תא דואר.
אפשר לעיין במאמר היקף הכיסוי של Address Validation API ובמאמר העזרה בנושא Address metadata .
|
הנכס uspsData
המאפיין הזה מספק מידע שימושי לכתובות למשלוח דואר בארצות הברית.
עם זאת, לא בטוח שהשדה יאוכלס במלואו בכל כתובת שאומתה על ידי השירות. לכן אין להסתמך על הנכס הזה בתור
הוא רק לאמת כתובות, אלא רק לבדוק את verdict
address
גם כן.
פרטים נוספים זמינים בקטע טיפול בכתובות בארצות הברית ובחומר העזר של UspsData .
|