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

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

راجِع درجة الدقة في الدليل المرجعي.

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

يعرض البيان السمة 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

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

يُرجى الاطّلاع على تغطية واجهة برمجة التطبيقات للتحقق من صحة العناوين ومرجع Address metadata.

السمة uspsData

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

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