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

تحتوي استجابة Address Validation API على الخصائص التالية ذات المستوى الأعلى:

{
  // Address details determined by the API.
  "address": {},
  // Validation verdict.
  "verdict": {},
  // 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"
}

السمة verdict

تلخّص السمة verdict نتائج التحقّق من صحة العنوان، ويجب أن تكون السمة الأولى التي يتم تقييمها عند إنشاء منطق التحقّق من صحة العنوان. يمكن أن تعرض السمة مجموعة متنوعة من الحقول، وذلك حسب جودة عنوان الإخراج. على سبيل المثال، يعرض ما يلي السمة verdict لعنوان ذي جودة جيدة، والتي تعرض الحقول التالية لهذا الطلب تحديدًا:

"verdict": {
  "inputGranularity": "PREMISE",
  "validationGranularity": "PREMISE",
  "geocodeGranularity": "PREMISE",
  "possibleNextAction": "ACCEPT",
  "addressComplete": true,
  "hasUnconfirmedComponents": false,
  "hasInferredComponents": true,
  "hasReplacedComponents": false
}

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

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

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

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

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

  • inputGranularity: يصف هذا الحقل مستوى التفاصيل التي تم جمعها من العنوان الذي تم إرساله إلى خدمة "التحقّق من صحة العنوان" في واجهة برمجة تطبيقات JavaScript لخرائط Google. يؤثّر مستوى تفاصيل العنوان في الطلب على مستوى تفاصيل العنوان في ردّ التحقّق. على سبيل المثال، لا يؤدي العنوان الذي يتضمّن inputGranularity أقل من PREMISE أقل من مستوى 0x0A إلى validationGranularity عادةً إلى مستوى PREMISE 0x0A.
  • validationGranularity: مستوى الدقة الذي يمكن أن تتحقّق منه خدمة "التحقّق من صحة العنوان" في Maps JavaScript API من صحة العنوان بالكامل. في معظم الحالات، يشير مستوى الدقة PREMISE أو SUB_PREMISE إلى عنوان عالي الجودة ومن المرجّح أن يكون قابلاً للتسليم.
  • استبدِل geocodeGranularity بوصف لمستوى تفاصيل الرمز الجغرافي المرتبط بالعنوان. على سبيل المثال، قد تشير سجلات Google إلى توفّر رقم شقة، ولكن ليس إلى موقع جغرافي دقيق لتلك الشقة المحدّدة داخل مجمع سكني كبير. في هذه الحالة، يكون validationGranularity هو SUB_PREMISE، بينما يكون geocodeGranularity هو 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
}
راجِع النتيجة في دليل المراجع.

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

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

السمتان address وaddressComponent

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

يمكنك الاطّلاع على Address في دليل المراجع.

السمة addressComponent هي مكوّن فرعي من address يوفّر قائمة مفصّلة بالعناصر أو المكوّنات الخاصة بالعنوان الذي عالجته خدمة "التحقّق من صحة العناوين" في Maps JavaScript API. تحدّد واجهة برمجة التطبيقات كل حقل من حقول المكوّنات من خلال اسمه ونوعه ومستوى تأكيده.

يمكنك الاطّلاع على addressComponent في دليل المراجع.

السمة geocode

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

يمكنك الاطّلاع على Geocode في دليل المراجع.

السمة metadata

قد لا يتم ملء هذه السمة لكل عنوان تتم معالجته من خلال خدمة "التحقّق من صحة العنوان" في Maps JavaScript API، ولكنها تشير إلى ما إذا كان العنوان من النوع السكني أو التجاري أو صندوق بريد.

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

السمة uspsData

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

اطّلِع على التعامل مع العناوين في الولايات المتحدة والمرجع الخاص بـ USPSData.