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

توفّر Address Validation API نصّ الاستجابة بتنسيق كائن JSON يحتوي على سمتَين من المستوى الأعلى:

• result، كائن من النوع ValidationResult
• responseID

{
  "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 ولكن geocodeGranularityisالجزء الأول.

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

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

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

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

جودة العنوان

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

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

السمتَان address وaddressComponent

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

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

السمة geocode

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

سمة metadata

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

السمة uspsData

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