ה-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
– רמת הפירוט שבה ה-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 ו-כתובת במדריך. |
איכות הכתובת
יש כמה שדות אפשריים שמציינים בעיות ברכיבי הכתובת או שינויים בהם, כמו רכיבי כתובת שהוסקו או חסרים. לדוגמה, המאפיין 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 לאימות כתובת, אבל הוא מציין אם הכתובת היא מסוג כתובת מגורים, עסק או תיבת דואר.
מידע נוסף זמין בקטע הכיסוי של ה-API לאימות כתובות ובחומר העזר בנושא Address metadata .
|
הנכס uspsData
המאפיין הזה מספק מידע שימושי לכתובות למשלוח דואר בארצות הברית.
עם זאת, לא בטוח שהוא יאוכלס במלואו לכל כתובת שאומתה על ידי השירות. לכן, לא מומלץ להסתמך על המאפיין הזה כאמצעי היחיד לאימות כתובות, אלא גם את verdict
ואת address
.
פרטים נוספים זמינים בקטע טיפול בכתובות בארצות הברית ובחומר העזר של UspsData .
|