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

توفّر واجهة برمجة التطبيقات 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,
  "possibleNextAction": "ACCEPT"
}

تلخّص الأقسام التالية جميع الحقول في السمة verdict.

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

الإجراء التالي المحتمل

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

مستوى تفاصيل العنوان

تشير دقة العنوان إلى مستوى التفاصيل المستخدَمة في تحديد مدى دقة العنوان أو الرمز الجغرافي. تُعدّ دقة العنوان في الردّ 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,
    "possibleNextAction": "ACCEPT"
}

عندما يكون العنوان الجغرافي يتضمّن مكوّنات غير متوفّرة أو لم يتم حلّها أو غير متوقّعة، يتم ضبط الحقل على 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.
السابق
إرسال طلب التحقق من العنوان
التالي
بناء منطق التحقق من الصحة