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

دليل حلّ مشكلة التحقّق من العنوان

مخطّط انسيابي يعرض نظرة عامة شاملة على خطوات الاختبار

الهدف

توفّر واجهة Address Validation قيمة لمجموعة متنوعة من حالات الاستخدام، وهناك اعتبارات رئيسية ننصحك باستكشافها تتجاوز الجودة الأولية لنتائج الاختبار. على سبيل المثال: نظرة شاملة على المنتجات المتوافقة في مسار المستخدم، مثل الإكمال التلقائي للأماكن وخرائط Google، ومدى التوفّر على المستوى الإقليمي، والثقة والموثوقية على مستوى المؤسسة.

بعد الوصول إلى مرحلة تقييم Address Validation API، إليك بعض الإرشادات التي ننصحك باتّباعها كجزء من عملية الاختبار.

ستكون أهداف هذا الاختبار هي:

تأكَّد من أنّ Address Validation API مناسبة لحالة الاستخدام.
تحقَّق من مدى تلبية Address Validation API لمتطلبات الحلول، مثل:
- تحديد العناوين ذات الجودة العالية
- التنبيه لمعالجة المدخلات ذات الجودة الرديئة.
- إجراء تصحيحات على بيانات العناوين، بما في ذلك الاستنتاجات والاستبدالات وتصحيحات الأخطاء الإملائية
- تقديم عنوان منسَّق للشحن
- التنبيه إلى بيانات المباني الفرعية المفقودة أو غير الصحيحة (الولايات المتحدة فقط)
تأكَّد من أنّك ستحصل على فائدة قابلة للقياس من تنفيذ واجهة برمجة التطبيقات.

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

تجهيز بياناتك

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

استخدِم العناوين من نقطة الالتقاط. على سبيل المثال، إذا كنت تخطط لتنفيذ ميزة التحقق من العنوان في صفحة الدفع في التجارة الإلكترونية، فاستخدم العناوين كما أدخلها عملاؤك في النموذج، قبل إجراء أي معالجة حالية قد يتم استبدالها بتنفيذ واجهة برمجة تطبيقات التحقق من العنوان.

جهِّز عيّنة من حوالي 5,000 إلى 10,000 سجلّ للاختبار.

استدعاء واجهة برمجة التطبيقات

شرط أساسي لهذا القسم: فهم كيفية إرسال طلب للتحقّق من صحة العنوان

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

يمكنك الاطّلاع على مستندات Address Validation API للحصول على إرشادات حول كيفية طلب واجهة برمجة التطبيقات. لدينا أيضًا مقالة توضّح أفضل الممارسات لاستخدام Address Validation API لمعالجة العناوين بكميات كبيرة.

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

مراجعة النتائج

متطلبات القسم: فهم كيفية التعامل مع استجابة التحقّق، خاصةً مفهوم "الإصلاح" و"التأكيد" و"القبول".

في هذا القسم، سنناقش سيناريوهات المخرجات التي يمكنك تحليلها لتقييم مدى ملاءمة الحل.

نظرة عامة على حقول واجهة برمجة التطبيقات الرئيسية التي تمت مناقشتها في هذا المستند

بيانات الردود	ما هي؟	كيفية التقييم	كيف تساعدك هذه الميزة؟
verdict.inputGranularity	يصف هذا الحقل دقة الإدخال للعنوان.	SUB_PREMISE PREMISE PREMISE_PROXIMITY حظر ROUTE OTHER	تتيح لك تحديد ما إذا كان العنوان الذي تم إدخاله يحتوي على بيانات كافية ليكون صالحًا.
verdict.validationGranularity	يصف عملية التحقّق من صحة الناتج الإجمالي للعنوان.	SUB_PREMISE PREMISE PREMISE_PROXIMITY حظر ROUTE OTHER	تتيح لك تحديد الجودة الإجمالية للعناوين في النتائج التي تعرضها واجهة برمجة التطبيقات.
verdict.hasInferredComponents	تشير إلى ما إذا كانت واجهة برمجة التطبيقات قد استنتجت مكوّنًا.	صحيح/خطأ	يمكن لواجهة برمجة التطبيقات إضافة المكوّنات الناقصة عندما تتمكّن من استنتاج البيانات. على سبيل المثال، رمز الولاية غير متوفّر.
verdict.hasReplacedComponents	تشير إلى ما إذا كانت واجهة برمجة التطبيقات قد استبدلت مكوّنًا.	صحيح/خطأ	يمكن لواجهة برمجة التطبيقات استبدال المكوّنات غير الصحيحة بالبيانات الصحيحة في بعض السيناريوهات.
verdict.addressComplete	تشير إلى ما إذا كان العنوان مكتملاً.	صحيح/خطأ	إذا حدّدت واجهة برمجة التطبيقات أنّ العنوان الناتج يتضمّن جميع المكوّنات اللازمة، ستكون هذه القيمة صحيحة.
address.missingComponentTypes	إشارة للتحذير في حال عدم توفّر عناصر في العنوان	يُرجى الاطّلاع على الجدول الثاني لمعرفة القيم.	تمييز المكوّنات غير المتوفّرة في عنوان غير مكتمل

مراجعة العناوين الصالحة

رتِّب البيانات التي تم عرضها من واجهة برمجة التطبيقات لتحديد مجموعة العناوين التي سيقبلها نظامك على أنّها صالحة. في ما يلي الإشارات الرئيسية التي يجب البحث عنها من واجهة برمجة التطبيقات:

يحتوي "verdict.validationGranularity" على "PREMISE" أو أفضل.
verdict.addressComplete هي true.
لا تتوفّر مكوّنات مستنتَجة أو مستبدَلة.

يُرجى الاطّلاع على قبول عنوان لمزيد من المعلومات.

يجب أن تكون مخرجات هذا التمرين مجموعة فرعية من بيانات العناوين التي سيتم قبولها كصالحة من قِبل نظامك. في هذه المرحلة، يمكنك تحديد:

هل نسبة القبول مقبولة؟
إذا كنت تستخدم سير عمل حاليًا للتحقّق من العناوين، هل معدّل القبول مكافئ أو أفضل؟

مثال: عنوان صالح

العنوان الذي تم إدخاله	الإقليم
76 Buckingham Palace Road, London SW1W 9TQ	المملكة المتحدة

القرار

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

مراجعة العناوين غير الصالحة

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

رتِّب البيانات التي تم عرضها من واجهة برمجة التطبيقات لتحديد مجموعة العناوين التي سيصنّفها نظامك على أنّها غير صالحة. في ما يلي الإشارات الرئيسية التي يجب البحث عنها من واجهة برمجة التطبيقات:

يجب ضبط verdict.validationGranularity على OTHER أو ROUTE حسب مستوى الخطورة.
verdict.addressComplete هي false.

يمكنك الاطّلاع على تصحيح عنوان لمزيد من المعلومات.

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

من المهم الإشارة إلى أنّ وضع علامة على العناوين بأنّها غير صالحة هو جزء أساسي من وظائف Address Validation API، ولا يشير بالضرورة ارتفاع معدّل العناوين التي تم وضع علامة عليها بأنّها غير صالحة إلى ضعف أداء واجهة برمجة التطبيقات. تمنحك واجهة برمجة التطبيقات معلومات تفيد بوجود خطأ في العنوان، وقد يؤدي ذلك إلى زيادة الكفاءة في سير العمل من خلال اكتشاف الأخطاء في وقت مبكر، قبل أن تتسبب في حدوث مشكلات في المراحل اللاحقة.

مثال: عنوان غير صالح

العنوان الذي تم إدخاله	الإقليم
‫21 45 40th street	الولايات المتحدة الأمريكية

القرار

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

مراجعة المكوّنات غير المتوفّرة أو غير المؤكّدة

في هذه المرحلة، يمكن أيضًا مراجعة المكوّنات المفقودة أو غير المؤكّدة. هذا جزء من عنصر العنوان في الردّ. الحقلان هما missingComponentTypes وunconfirmedComponentTypes.

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

مثال: مكوّن مفقود وغير مؤكّد

العنوان الذي تم إدخاله	الإقليم
Fake St, New York, NY 10011	الولايات المتحدة الأمريكية

القرار

{
     "inputGranularity": "ROUTE",
     "validationGranularity": "OTHER",
     "geocodeGranularity": "OTHER",
     "hasUnconfirmedComponents": true
}

المكوّنات غير المتوفّرة وغير المؤكّدة

"missingComponentTypes": [
    "street_number"
],
"unconfirmedComponentTypes": [
    "route"
]

مراجعة العناوين التي تتضمّن تصحيحات

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

في ما يلي الإشارات الرئيسية التي يجب البحث عنها:

‫inferred أو replaced أو spellCorrected مضبوطة على true في أي من addressComponents.
‫verdict.hasInferredComponents أو verdict.hasReplacedComponents مضبوط على true.

لمزيد من المعلومات، يُرجى الاطّلاع على مقالة تأكيد عنوان.

يجب أن تكون نتيجة هذا التمرين مجموعة فرعية من بيانات العناوين التي تم تطبيق تصحيح عليها من خلال واجهة برمجة التطبيقات.

يمكن مراجعة جزء من هذه البيانات يدويًا لتحديد ما إذا كانت واجهة برمجة التطبيقات تُجري تصحيحات على بياناتك من شأنها تقليل المشاكل في سير العمل اللاحق.

مثال: عنوان يتضمّن تصحيحًا

العنوان الذي تم إدخاله	الإقليم
76 Bruckingm Palace Road, London SW1W 9TQ	المملكة المتحدة

المسار addressComponent

{
    "componentName": {
        "text": "Buckingham Palace Road",
        "languageCode": "en"
    },
    "componentType": "route",
    "confirmationLevel": "CONFIRMED",
    "spellCorrected": true
}

[الولايات المتحدة فقط] مراجعة العنوان الذي يتضمّن بيانات ناقصة أو غير صحيحة عن المبنى الفرعي

يمكن لواجهة Address Validation API تحديد ما إذا كان المبنى الفرعي غير متوفّر أو غير صحيح، وذلك للعناوين في الولايات المتحدة.

في ما يلي الإشارات الرئيسية التي يجب البحث عنها:

في عنصر العنوان:
- تحتوي السلسلة الفرعية "unconfirmedComponentTypes" على subpremise
- تحتوي السلسلة الفرعية "missingComponentTypes" على subpremise
في عنصر UspsData:
- ‫dpvConfirmation هو D (المبنى الفرعي غير متوفّر)
- ‫dpvConfirmation هو S (لم يتم تأكيد المبنى الفرعي)

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

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

مثال: عدم توفّر معلومات عن المبنى الفرعي

العنوان الذي تم إدخاله	الإقليم
‎111 8th Avenue, Manhattan, NY 10011	الولايات المتحدة

المكوّن غير متوفّر

"missingComponentTypes": [
    "subpremise"
]

تأكيد بيانات USPS DPV

"dpvConfirmation": "D"

[الولايات المتحدة فقط] مراجعة USPS standardizedAddress

تعرض واجهة Address Validation API أيضًا العنوان الموحّد وفقًا لخدمة USPS للعناوين في الولايات المتحدة. وهذا مهم بشكل خاص إذا كنت بحاجة إلى طباعة عناوين بتنسيق USPS على تصنيفات الحزم.

يمكن مراجعة UspsAddress للاطّلاع على هذه البيانات وتحديد ما إذا كانت تضيف قيمة إلى سير العمل.

مثال: عنوان موحّد من USPS

"standardizedAddress": {
    "firstAddressLine": "111 8TH AVE FL 11",
    "cityStateZipAddressLine": "NEW YORK NY 10011-5201",
    "city": "NEW YORK",
    "state": "NY",
    "zipCode": "10011",
    "zipCodeExtension": "5201"
}

الخاتمة

ابدأ الاختبار: ابدأ اختبار Address Validation API اليوم لضمان دقة بيانات العناوين وتحسين تجربة المستخدم وتبسيط عملياتك التجارية. بعد اتّباع سيناريوهات الاختبار الموضّحة أعلاه، ستتوفّر لديك المعلومات اللازمة لتحديد ما إذا كانت Address Validation API ستضيف قيمة إلى سير العمل.

قراءات إضافية مقترَحة:

المساهمون

هنريك فالف | مهندس DevX

دليل حلّ مشكلة التحقّق من العنوان تنظيم صفحاتك في مجموعات يمكنك حفظ المحتوى وتصنيفه حسب إعداداتك المفضّلة.

الهدف

تجهيز بياناتك

استدعاء واجهة برمجة التطبيقات

مراجعة النتائج

مراجعة العناوين الصالحة

مثال: عنوان صالح

مراجعة العناوين غير الصالحة

مثال: عنوان غير صالح

مراجعة المكوّنات غير المتوفّرة أو غير المؤكّدة

مثال: مكوّن مفقود وغير مؤكّد

مراجعة العناوين التي تتضمّن تصحيحات

مثال: عنوان يتضمّن تصحيحًا

[الولايات المتحدة فقط] مراجعة العنوان الذي يتضمّن بيانات ناقصة أو غير صحيحة عن المبنى الفرعي

مثال: عدم توفّر معلومات عن المبنى الفرعي

[الولايات المتحدة فقط] مراجعة USPS standardizedAddress

مثال: عنوان موحّد من USPS

الخاتمة

المساهمون

دليل حلّ مشكلة التحقّق من العنوان