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