تمت ترجمة هذه الصفحة بواسطة Cloud Translation API‏.

اختيار حلّ التحقّق من العنوان

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

الهدف

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

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

تهدف هذه التجربة إلى ما يلي:

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

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

إعداد بياناتك

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

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

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

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

شرط أساسي: تعرَّف على كيفية إرسال طلب التحقّق من العنوان.

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

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

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

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

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

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

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

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

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

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

يحتوي على 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"
]

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

"dpvConfirmation": "D"

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

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

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

مثال: عنوان موحّد وفقًا لمعايير خدمة البريد الأمريكية

"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 ستضيف قيمة إلى سير عملك.

محتوى إضافي للقراءة:

المساهمون

هنريك فالف | مهندس تجربة المطوّرين

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

الهدف

إعداد بياناتك

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

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

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

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

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

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

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

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

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

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

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

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

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

مثال: عنوان موحّد وفقًا لمعايير خدمة البريد الأمريكية

الخاتمة

المساهمون

اختيار حلّ التحقّق من العنوان