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

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

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

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

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

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

جودة العنوان

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

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

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

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

السمتان address وaddressComponent

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

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

السمة geocode

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

السمة metadata

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

السمة uspsData

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