توفّر واجهة برمجة تطبيقات التحقق من صحة العنوان نص استجابة بتنسيق 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
— يصف مستوى التفاصيل التي يتم الحصول عليها من العنوان المرسل إلى واجهة برمجة تطبيقات التحقق من صحة العنوان. مستوى تفاصيل العنوان في الطلب على مستوى تفاصيل العنوان في استجابة التحقق من الصحة. على سبيل المثال، عنوان لهinputGranularity
أقل منPREMISE
أدناه لا يؤدي عادةً إلى الانتقال منvalidationGranularity
إلىPREMISE
. المستوى.validationGranularity
: مستوى الدقّة الذي يمكن لواجهة برمجة تطبيقات التحقق من صحة العنوان التحقُّق من صحة العنوان بشكل كامل. في معظم الحالات، يشير مستوى الدقةPREMISE
أوSUB_PREMISE
إلى عنوان الجودة الذي من المحتمل أن يتم تسليمه.geocodeGranularity
— لوصف مستوى تفاصيل الرمز الجغرافي المرتبط بالعنوان. على سبيل المثال، قد تشير سجلات Google إلى أن وجود رقم شقة، لكن ليس الموقع الدقيق لذلك شقة معينة داخل مجمع سكني كبير. في هذه الحالة،validationGranularity
هوSUB_PREMISE
ولكنgeocodeGranularity
is
الجزء الأول.
عرض درجة الدقة في الدليل المرجعي. |
اكتمال العنوان
يعرض البيان السمة 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
يوفّر
قائمة مفصلة بالعناصر أو المكونات الخاصة بالعنوان الذي
تمت معالجة واجهة برمجة تطبيقات التحقق من صحة العنوان. تحدد واجهة برمجة التطبيقات كل مكون
حسب الاسم والنوع ومستوى التأكيد.
اطّلِع على addressComponent في الدليل المرجعي. |
السمة geocode
تشير السمة geocode
إلى الموقع المرمّز جغرافيًا المرتبط بالإدخال.
الخاص بك. تقدّم هذه السمة تفاصيل حول الموقع الجغرافي نفسه، مثل
معرّف مكانه.
اطّلِع على Geocode في الدليل المرجعي. |
السمة metadata
قد لا تتم تعبئة هذه السمة لكل عنوان تتم معالجته من خلال واجهة برمجة تطبيقات التحقق من صحة العناوين، ولكنها تشير إلى ما إذا كان العنوان سكنيًا، أو الشركة أو صندوق البريد.
يُرجى الاطّلاع على تغطية واجهة برمجة التطبيقات للتحقق من صحة العناوين ومرجع Address metadata .
|
السمة uspsData
تقدّم هذه السمة معلومات مفيدة للعناوين البريدية في الولايات المتحدة.
ومع ذلك، ليس مضمونًا أن تتم تعبئتها بالكامل لكل عنوان تم التحقّق من صحته.
حسب الخدمة. لهذا السبب، يجب ألّا تعتمد على هذه السمة على أنّها
فقط التحقق من العناوين، ولكن بدلاً من ذلك، يمكنك التحقق من verdict
address
أيضًا.
يُرجى الاطّلاع على التعامل مع العناوين في الولايات المتحدة ومرجع UspsData .
|