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

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

السمتان address وaddressComponent

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

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

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

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

السمة geocode

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

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

السمة metadata

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

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

السمة uspsData

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

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