ה-Address Validation 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
.
מידע נוסף זמין בקטע Verdict במדריך העזרה. |
רמת פירוט הכתובת
רמת הפירוט של כתובת מתייחסת לרמת הפירוט שמשמשת לקביעת הספציפיות של כתובת או של קוד גיאוגרפי. ספציפיות של כתובות
התשובה validationGranularity
היא אות חשוב שמציין אם כתובת או לא
הוא ניתן להעלאה.
המאפיין verdict
מחזיר את אותות הפירוט הבאים:
inputGranularity
– מתאר את רמת הפירוט שתועדה שנשלחה לממשק ה-API של אימות כתובת. רמת פירוט הכתובת בבקשה משפיעה על רמת פירוט הכתובת בתשובה לאימות. לדוגמה, כתובת עםinputGranularity
מתחת ל-PREMISE
בדרך כלל לא מסתיים ב-validationGranularity
עדPREMISE
ברמה.validationGranularity
– רמת הפירוט של ה-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 (תוצאת הבדיקה) ובקטע Address (כתובת) במדריך העזר. |
איכות הכתובת
יש כמה שדות אפשריים שמציינים בעיות ברכיבי הכתובת או התאמות שלהם, כמו רכיבי כתובת חסרים או רכיבי כתובת שהמערכת הסיקה. לדוגמה, המאפיין verdict
הבא מציין כתובת עם רכיבים לא מאומתים ושדה addressComplete
חסר:
"verdict": {
"inputGranularity": "PREMISE",
"validationGranularity": "OTHER",
"geocodeGranularity": "OTHER",
"hasUnconfirmedComponents": true,
"hasInferredComponents": true
}
מידע נוסף זמין בקטע Verdict במדריך העזרה. |
המאפיינים address
ו-addressComponent
המאפיין address
מספק עיצוב לכתובת שעברה עיבוד שצוינה בבקשה, יחד עם סיכומים של הכתובת ברמת הרכיבים, כולל חלקים בכתובת עם שגיאות איות, חלקים שגויים שהוחלפו וחלקים חסרים שהמערכת הסיקה.
מידע נוסף זמין במאמר Address במדריך העזרה. |
המאפיין addressComponent
הוא רכיב משנה של address
שמספק
רשימה מפורטת של הרכיבים או הרכיבים של הכתובת
הסתיים העיבוד של ה-API לאימות כתובת. ה-API מזהה כל רכיב
מצוין לפי השם, הסוג ורמת האישור שלו.
ראו addressComponent במדריך האישי. |
הנכס geocode
המאפיין geocode
מציין את המיקום המקודד שמשוייך לכתובת שהוזנה. המאפיין הזה מספק פרטים על המיקום עצמו, כמו מזהה המקום.
מידע נוסף זמין במאמר Geocode במדריך העזרה. |
הנכס metadata
יכול להיות שהנכס הזה לא יאוכלס בכל כתובת שעוברת עיבוד על ידי Address Validation API, אבל הוא מציין אם הכתובת היא מסוג מגורים, עסק או תיבת דואר.
אפשר לעיין במאמר היקף הכיסוי של Address Validation API ובמאמר העזרה בנושא Address metadata .
|
הנכס uspsData
הנכס הזה מספק מידע שימושי לגבי כתובות דואר בארצות הברית.
עם זאת, לא בטוח שהשדה הזה מאוכלס במלואו עבור כל כתובת שאומתה.
על ידי השירות. לכן אין להסתמך על הנכס הזה בתור
הוא רק לאמת כתובות, אלא רק לבדוק את verdict
address
גם כן.
אפשר לעיין במאמר טיפול בכתובות בארה"ב ובחומר העזר בנושא UspsData .
|