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

توفّر واجهة برمجة التطبيقات للتحقّق من العنوان نص استجابة على شكل كائن 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
}

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

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

درجة دقة العنوان

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

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

  • inputGranularity - يصف مستوى التفاصيل التي تم تسجيلها من العنوان المُرسل إلى واجهة برمجة التطبيقات للتحقق من صحة العنوان. يؤثر مستوى تفاصيل العنوان في الطلب على مستوى تفاصيل العنوان في رد التحقق. على سبيل المثال، إذا كان العنوان يتضمّن inputGranularity أقل من PREMISE، لا يؤدي عادةً إلى تغيير المستوى من validationGranularity إلى PREMISE.
  • validationGranularity: مستوى الدقة الذي يمكن لواجهة برمجة تطبيقات التحقّق من صحة العنوان من خلاله إثبات صحة العنوان بشكل كامل. في معظم الحالات، يشير مستوى الدقة PREMISE أو SUB_PREMISE إلى عنوان عالي الجودة من المُرجَّح أنّه قابل للتسليم.
  • geocodeGranularity - يصف مستوى تفاصيل الرمز الجغرافي المرتبط بالعنوان. على سبيل المثال، قد تشير سجلات Google إلى وجود رقم شقة، ولكن ليس الموقع الدقيق لهذه الشقة الخاصة داخل مجمع سكني كبير. في هذه الحالة، تكون القيمة validationGranularity هي SUB_PREMISE ولكن القيمة geocodeGranularityisPREMISE`.
اطّلِع على مستوى الدقة في الدليل المرجعي.

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

يعرض القرار السمة 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 الذي يوفر قائمة مفصّلة بالعناصر أو مكوّنات العنوان الذي عالجته واجهة برمجة التطبيقات الخاصة بالتحقّق من صحة العنوان. تحدد واجهة برمجة التطبيقات كل حقل مكون يوفره الاسم والنوع ومستوى التأكيد.

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

السمة "geocode"

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

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

السمة "metadata"

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

اطّلِع على تغطية واجهة برمجة التطبيقات Accessibility Verification API ومرجع Address metadata.

السمة "uspsData"

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

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