فهم أحد الردود الأساسية للتحقّق من صحة العنوان

توفّر 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 — يصف مستوى التفاصيل الذي يتم الحصول عليه من العنوان المُرسَل إلى واجهة برمجة تطبيقات التحقق من صحة العنوان. يؤثر مستوى تفاصيل العنوان في الطلب في مستوى تفاصيل العنوان في ردّ عملية التحقّق. على سبيل المثال، لا يؤدي عادةً عنوان يتضمن inputGranularity أقل من PREMISE في المستوى إلى validationGranularity إلى PREMISE.
• ‫validationGranularity: مستوى الدقة الذي يمكن فيه لواجهة برمجة التطبيقات Address Validation API التحقّق من صحة العنوان بالكامل. في معظم الحالات، يشير مستوى الدقة PREMISE أو SUB_PREMISE إلى عنوان ذو جودة يُحتمل أن يكون قابلاً للتسليم.
• ‫geocodeGranularity: يصف مستوى تفاصيل الرمز الجغرافي المرتبط بالعنوان. على سبيل المثال، قد تشير سجلات Google إلى توفّر رقم شقة، ولكن ليس الموقع الجغرافي الدقيق لتلك الشقة المحدّدة ضمن مجمع سكني كبير. في هذه الحالة، يكون validationGranularity هو SUB_PREMISE ولكن geocodeGranularityisPREMISE`.

اكتمال العنوان

يعرض البيان الخاص بالعنوان الخاص بـ addressComplete إشارة تدل على أنّه عنوان عالي الجودة، ما يعني تحديدًا أنّه لا يحتوي على أيّ مكونات مفقودة أو غير محدّدة أو غير متوقّعة:

"verdict": {
    "inputGranularity": "PREMISE",
    "validationGranularity": "PREMISE",
    "geocodeGranularity": "PREMISE",
    "addressComplete": true
}

عندما يتضمّن العنوان مكوّنات غير متوفّرة أو غير محدّدة أو غير متوقّعة، يتم ضبط الحقل على false.

جودة العنوان

يشير عدد من الحقول المحتمَلة إلى مشاكل في مكونات العنوان أو تعديلات عليها، مثل مكونات العنوان المستنتَجة أو غير المتوفّرة. على سبيل المثال، تشير السمة verdict التالية إلى عنوان يتضمّن مكوّنات غير مؤكَّدة وحقل addressComplete غير متوفّر:

"verdict": {
    "inputGranularity": "PREMISE",
    "validationGranularity": "OTHER",
    "geocodeGranularity": "OTHER",
    "hasUnconfirmedComponents": true,
    "hasInferredComponents": true
}

السمتَان address وaddressComponent

يوفّر السمة address تنسيقًا للعنوان الذي تمت معالجته والمقدَّم في الطلب، بالإضافة إلى ملخّصات على مستوى المكوّنات للعنوان، بما في ذلك الأجزاء التي تحتوي على أخطاء إملائية في العنوان والأجزاء غير الصحيحة التي تم استبدالها والأجزاء المفقودة التي تم استنتاجها .

سمة addressComponent هي مكوّن فرعي لسمة address التي تقدّم قائمة تفصيلية بالعناصر أو المكوّنات للعنوان الذي تمت معالجته من خلال Address Validation API. تُحدِّد واجهة برمجة التطبيقات كلّ عنصر يقدّمه الحقل، وذلك حسب اسمه ونوعه ومستوى التأكيد.

سمة geocode

تشير السمة geocode إلى الموقع الجغرافي المشفَّر جغرافيًا والمرتبط بعنوان الإدخال. تقدّم هذه السمة تفاصيل عن الموقع الجغرافي نفسه، مثل رقم تعريف المكان.

سمة metadata

قد لا يتم تعبئة هذه السمة لكل عنوان تعالجّه واجهة برمجة التطبيقات Address Validation API، ولكنها تشير إلى ما إذا كان العنوان من النوع السكني أو النشاط التجاري أو صندوق البريد.

سمة uspsData

تقدّم هذه السمة معلومات مفيدة للعناوين البريدية في الولايات المتحدة. ومع ذلك، لا يمكن ضمان تعبئة هذه السمة بالكامل لكل عنوان تُجري الخدمة عملية التحقّق منه. لهذا السبب، يجب عدم الاعتماد على هذا السمة كأحد الوسائل الوحيدة للتحقّق من صحة العناوين، بل يجب التحقّق من verdict و address أيضًا.