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

يحتوي ردّ من واجهة برمجة التطبيقات 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: يصف مستوى التفاصيل التي تم تسجيلها من العنوان المُرسَل إلى Address Validation في 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.

جودة العنوان

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

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

الإجراء التالي المحتمل

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

السمتان address وaddressComponent

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

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

السمة geocode

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

السمة metadata

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

السمة uspsData

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