يصف هذا المستند عددًا من السيناريوهات الواقعية التي توفّر فيها Address Validation API إشارات استجابة تتطلّب سلوك إصلاح من نظامك. الأمثلة الواردة هنا توضيحية وليست شاملة. يُرجى الاطّلاع على نظرة عامة على سير العمل في إنشاء منطق التحقّق للحصول على السياق.
أمثلة شائعة: الإصلاح
يصف هذا القسم الأمثلة الشائعة التي توفّر فيها Address Validation API إشارات استجابة تشير إلى معلومات عنوان أقل جودة.
المدينة والرمز البريدي غير متوفّرَين
يوضّح هذا المثال إدخالاً يحتوي على عنوان الشارع فقط، بدون مدينة أو رمز بريدي.
| العنوان الذي تم إدخاله | المنطقة |
|---|---|
| 21 45 40th street | الولايات المتحدة الأمريكية |
القرار بشأن عدم توفّر المدينة والرمز البريدي
يؤكّد المثال أدناه على الإشارات المهمة من الردّ.
{
"inputGranularity": "PREMISE",
"validationGranularity": "OTHER",
"geocodeGranularity": "OTHER",
"hasUnconfirmedComponents": true
}
تشير هذه الإشارات إلى عنوان غير قابل للتسليم، لذا يمكنك الاستعلام عن
addressComponents لمعرفة المزيد:
{
"componentName": {
"text": "21",
"languageCode": "en"
},
"componentType": "street_number",
"confirmationLevel": "UNCONFIRMED_BUT_PLAUSIBLE"
},
{
"componentName": {
"text": "45 40th street",
"languageCode": "en"
},
"componentType": "route",
"confirmationLevel": "UNCONFIRMED_BUT_PLAUSIBLE"
},
{
"componentName": {
"text": "United States",
"languageCode": "en"
},
"componentType": "country",
"confirmationLevel": "CONFIRMED"
}
تعرض واجهة Address Validation API البلد (الولايات المتحدة) فقط على النحو التالي: CONFIRMED.
وتعرض جميع مكوّنات العناوين الأخرى على أنّها UNCONFIRMED_BUT_PLAUSIBLE، مع
بعض عمليات الحذف المهمة للبيانات، مثل المنطقة والرمز البريدي.
رقم الشارع غير متوفّر
يعرض هذا المثال رقم شارع مفقودًا.
| العنوان الذي تم إدخاله | المنطقة |
|---|---|
| Buckingham Palace Road, SW1W 9TQ London | المملكة المتحدة |
القرار بشأن رقم الشارع غير المتوفّر
{
"inputGranularity": "PREMISE_PROXIMITY",
"validationGranularity": "ROUTE",
"geocodeGranularity": "ROUTE"
}
قيمة validationGranularity هي ROUTE، ما يشير إلى تطابق مع الشارع،
ولكن لا تتوفّر معلومات كافية للوصول إلى المبنى. بالإضافة إلى ذلك، لا تتضمّن النتيجة السمة addressComplete، وبالتالي فهي false. يكشف الاستعلام الإضافي عن الكائن address
عن نوع مكوّن مفقود:
"missingComponentTypes": [
"street_number"
]
أمثلة على الحالات الحدية: الإصلاح
في بعض الحالات، يعتمد قرارك بإصلاح عنوان أو تأكيده أو قبوله على سيناريو نشاطك التجاري المحدّد. توضح الأمثلة أدناه السيناريوهات التي قد لا تندرج بدقة في فئة الإصلاح.
رقم الشارع غير مؤكَّد
في هذا السيناريو، لا يمكن لواجهة Address Validation API تأكيد رقم الشارع المقدَّم، ومع ذلك تشير إلى أنّ العنوان مكتمل.
| العنوان الذي تم إدخاله | المنطقة |
|---|---|
| 84 Buckingham Palace Road, SW1W 9TQ, London | المملكة المتحدة |
Verdict for unconfirmed street number
يؤكّد المثال أدناه على الإشارات المهمة.
{
"inputGranularity": "PREMISE",
"validationGranularity": "PREMISE_PROXIMITY",
"geocodeGranularity": "PREMISE_PROXIMITY",
"addressComplete" : true,
"hasUnconfirmedComponents": true
}
من المفيد التحقّق من دقة التحقّق من الصحة فقط إلى
التقريب على مستوى المبنى مع المكونات غير المؤكدة. يُظهر طلب البحث عن السمة addressComponents ما يلي من componentType غير المؤكَّدة:
{
"componentName": {
"text": "84",
"languageCode": "en"
},
"componentType": "street_number",
"confirmationLevel": "UNCONFIRMED_BUT_PLAUSIBLE"
}
في هذه الحالة، يتم ضبط confirmation_level street_number على
UNCONFIRMED_BUT_PLAUSIBLE. تعني الحالة غير مؤكَّد أنّ الخدمة لا يمكنها مطابقة رقم الشارع 84 في مجموعة البيانات، وتعني الحالة مقبول أنّ بيانات المكوّن قد تظل صالحة.
لم يتم تضمين المبنى الفرعي
يصف هذا السيناريو عنوانًا لا يتضمّن سوى رقم فرعي، مثل رقم شقة أو قسم. وإلا، يمكن لواجهة Address Validation API التحقّق من صحة العنوان بالكامل. كما هو الحال عند عدم توفّر أي مكوّن من مكوّنات العنوان،
يكون addressComplete هو false، وبالتالي لا يظهر في الفحص اليدوي
للقرار.
على سبيل المثال، لنفترض أنّ أحد العملاء أدخل عنوانًا صالحًا لمكتب تقييم مدينة سان فرانسيسكو، ولكنّه لم يُدخل رقم الغرفة.
| العنوان الذي تم إدخاله | المنطقة |
|---|---|
| 1 Doctor Carlton B Goodlett Place, San Francisco, CA 94102 | الولايات المتحدة الأمريكية |
Verdict for missing subpremise
في هذا المثال، لا يعرض البيان السمة addressComplete، وبالتالي هو false. لهذا السبب، أنت تعلم أن عنصر عنوان واحد على الأقل
غير متوقع أو لم يتم حله أو مفقود.
{
"inputGranularity": "PREMISE",
"validationGranularity": "PREMISE",
"geocodeGranularity": "PREMISE",
"hasInferredComponents": true
}
يكشف طلب بحث address عما يلي:
"missingComponentTypes": [
"subpremise"
]
عند إجراء المزيد من الاستفسارات، توفّر بيانات USPS الرمز dpvConfirmation
D، والذي يشير أيضًا إلى عدم توفّر مبنى فرعي.