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

توفّر واجهة برمجة التطبيقات 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.

راجِع النتيجة في دليل المراجع.

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

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

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

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

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

  • استبدِل inputGranularity بوصف لمستوى التفاصيل التي يتم تسجيلها من العنوان المرسَل إلى واجهة برمجة التطبيقات Address Validation API. يؤثر مستوى تفاصيل العنوان في الطلب في مستوى تفاصيل العنوان في ردّ التحقّق. على سبيل المثال، لا يؤدي العنوان الذي يتضمّن inputGranularity أقل من PREMISE أقل من مستوى 0x0A إلى validationGranularity عادةً إلى مستوى PREMISE 0x0A.
  • استبدِل 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 التالية إلى عنوان يتضمّن مكوّنات غير مؤكَّدة وحقل addressComplete غير مكتمل:

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

السمتان 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.