توفّر واجهة برمجة التطبيقات للتحقّق من العنوان نص استجابة على شكل كائن 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
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
الذي يوفر قائمة مفصّلة بالعناصر أو مكوّنات العنوان الذي عالجته واجهة برمجة التطبيقات الخاصة بالتحقّق من صحة العنوان. تحدد واجهة برمجة التطبيقات كل حقل مكون
يوفره الاسم والنوع ومستوى التأكيد.
اطّلِع على addressComponent في الدليل المرجعي. |
السمة "geocode
"
تشير السمة geocode
إلى الموقع الجغرافي المشفّر المرتبط بعنوان الإدخال. تقدّم هذه السمة تفاصيل عن الموقع الجغرافي نفسه، مثل
معرّف المكان.
اطّلِع على Geocode في الدليل المرجعي. |
السمة "metadata
"
قد لا تتم تعبئة هذا الموقع لكل عنوان تتم معالجته من خلال واجهة برمجة التطبيقات للتحقق من العنوان، ولكنه يشير إلى ما إذا كان العنوان من النوع سكني أو نشاط تجاري أو صندوق بريد.
اطّلِع على تغطية واجهة برمجة التطبيقات Accessibility Verification API ومرجع Address metadata .
|
السمة "uspsData
"
تقدّم هذه السمة معلومات مفيدة للعناوين البريدية في الولايات المتحدة.
ومع ذلك، لا يمكن ضمان تعبئتها بالكامل لكل عنوان تم التحقُّق منه من خلال الخدمة. لهذا السبب، يجب عدم الاعتماد على هذه السمة
باعتبارها الوسيلة الوحيدة للتحقّق من العناوين، بل يمكنك بدلاً من ذلك التحقق من verdict
و
address
أيضًا.
يُرجى الاطّلاع على التعامل مع العناوين في الولايات المتحدة والمرجع UspsData .
|