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

توفّر Address Validation API نص الاستجابة بتنسيق كائن JSON يحتوي على سمتَين من المستوى الأعلى:

{
  "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.

راجِع Verdict في الدليل المرجعي.

دقة العنوان

تشير دقة العنوان إلى مستوى التفاصيل المستخدَمة في تحديد مدى دقة عنوان أو رمز جغرافي. إنّ تحديد العنوان في استجابة validationGranularity هو إشارة رئيسية لمعرفة ما إذا كان بالإمكان إرسال الرسالة إلى العنوان أم لا.

تعرِض السمة verdict إشارات الدّقة التالية:

  • ‫inputGranularity: يصف مستوى التفاصيل التي تم تسجيلها من عنوان العميل المُرسَل إلى Address Validation API. يؤثر مستوى تفاصيل العنوان في الطلب في مستوى تفاصيل العنوان في ردّ عملية التحقّق. على سبيل المثال، لا يؤدي عادةً عنوان يحتوي على 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.

راجِع addressComplete ضمن Verdict و العنوان في الدليل المرجعي.

جودة العنوان

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

"verdict": {
    "inputGranularity": "PREMISE",
    "validationGranularity": "OTHER",
    "geocodeGranularity": "OTHER",
    "hasUnconfirmedComponents": true,
    "hasInferredComponents": true
}
راجِع Verdict في الدليل المرجعي.

السمتَان address وaddressComponent

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

راجِع Address في الدليل المرجعي.

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

راجِع addressComponent في الدليل المرجعي.

سمة geocode

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

راجِع Geocode في الدليل المرجعي.

سمة metadata

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

اطّلِع على تغطية Address Validation API والمرجع Address metadata.

سمة uspsData

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

يُرجى الاطّلاع على معالجة عناوين الولايات المتحدة والمرجع UspsData.
السابق
إرسال طلب التحقق من العنوان
التالي
بناء منطق التحقق من الصحة