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

يحتوي ردّ 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 لعنوان بجودة جيدة، ما يؤدي إلى عرض 4 حقول لهذا الطلب المحدّد:

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

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

اطّلِع على الحكم في الدليل المرجعي.

تفاصيل العنوان

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

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

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

راجِع addressComplete ضمن الحكم و العنوان في الدليل المرجعي.

جودة العنوان

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

"verdict": {
    "inputGranularity": "PREMISE",
    "validationGranularity": "OTHER",
    "geocodeGranularity": "OTHER",
    "hasUnconfirmedComponents": true,
    "hasInferredComponents": true
}
اطّلِع على الحكم في الدليل المرجعي.

السمتَان address وaddressComponent

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

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

سمة addressComponent هي مكوّن فرعي لسمة address التي تقدّم قائمة تفصيلية بالعناصر أو المكوّنات للعنوان الذي تمت معالجته من خلال ميزة "إثبات صحة العنوان" في واجهة برمجة التطبيقات JavaScript لـ "خرائط Google". تُحدِّد واجهة برمجة التطبيقات كلّ عنصر يقدّمه الحقل، وذلك حسب اسمه ونوعه ومستوى التأكيد.

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

سمة geocode

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

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

سمة metadata

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

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

سمة uspsData

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

يُرجى الاطّلاع على معالجة عناوين الولايات المتحدة والرجوع إلى USPSData.