يوضّح هذا المستند عددًا من السيناريوهات الواقعية التي توفِّر فيها واجهة برمجة التطبيقات للتحقّق من صحة العناوين إشارات استجابة تتطلّب اتخاذ إجراء fix من نظامك. للحصول على السياق، يمكنك الاطّلاع على نظرة عامة على سير العمل ضمن إنشاء منطق التحقق.
أمثلة شائعة: الحل
يوضّح هذا القسم أمثلة شائعة تقدّم فيها "واجهة برمجة التطبيقات للتحقّق من العنوان" إشارات استجابة تشير إلى معلومات عناوين ذات جودة أقل.
يجب إدخال المدينة والرمز البريدي
يوضح هذا المثال إدخالاً يحتوي على عنوان الشارع فقط، بدون مدينة أو رمز بريدي.
تم إدخال العنوان. | المنطقة |
---|---|
21 45 40 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"
}
تعرض واجهة برمجة التطبيقات للتحقق من صحة العنوان البلد (الولايات المتحدة) فقط بالتنسيق CONFIRMED
.
وتعرض جميع مكونات العنوان الأخرى مثل UNCONFIRMED_BUT_PLAUSIBLE
، مع
بعض عمليات الحذف المهمة للبيانات، مثل المنطقة المحلية والرمز البريدي.
يجب إدخال رقم الشارع
يوضح هذا المثال رقم شارع غير موجود.
تم إدخال العنوان. | المنطقة |
---|---|
طريق قصر باكنغهام، SW1W 9TQ لندن | المملكة المتحدة |
قرار عدم إدراج رقم الشارع
{
"inputGranularity": "PREMISE_PROXIMITY",
"validationGranularity": "ROUTE",
"geocodeGranularity": "ROUTE"
}
قيمة validationGranularity
هي ROUTE
، ما يشير إلى تطابق مع الشارع، ولكن لا تتوفر معلومات كافية للوصول إلى المبنى. بالإضافة إلى ذلك، لا يتضمّن البيان
السمة addressComplete
، وبالتالي هي
false
. يكشف الاستعلام الإضافي عن الكائن address
عن نوع مكون مفقود:
"missingComponentTypes": [
"street_number"
]
أمثلة على حالة الحافة: الإصلاح
في بعض الحالات، يعتمد إصلاح العنوان أو تأكيده أو قبوله على سيناريو نشاطك التجاري تحديدًا. توضح الأمثلة أدناه السيناريوهات التي قد لا تندرج بشكل صارم في فئة الإصلاح.
لم يتم تأكيد رقم الشارع
في هذا السيناريو، لا يمكن لواجهة برمجة التطبيقات التحقق من العنوان تأكيد رقم الشارع الذي تم إدخاله، إلا أنها تشير إلى اكتمال العنوان.
تم إدخال العنوان. | المنطقة |
---|---|
84 Buckingham Palace Road, SW1W 9TQ, London | المملكة المتحدة |
قرار بشأن رقم شارع غير مؤكد
يؤكد المثال أدناه على الإشارات المهمة.
{
"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 في مجموعة البيانات، وتعني الحالة معقولة أنّ بيانات المكوّنات لا تزال صالحة.
البداية الفرعية غير متوفرة
يصف هذا السيناريو عنوانًا يفتقد إلى مبنى فرعي فقط، مثل
رقم الشقة أو القسم. وإلا، يمكن لواجهة برمجة تطبيقات التحقق من صحة العنوان
التحقق بشكل كامل من العنوان. كما هي الحال في حال عدم توفّر أي مكوّن عنوان، تكون السمة addressComplete
هي false
، وبالتالي لا تكون متوفرة عند الفحص اليدوي للبيان.
لتوضيح، افترض أن أحد العملاء أدخل عنوانًا صالحًا لمكتب مقيّم مدينة سان فرانسيسكو، ولكنه أغفل رقم الغرفة من الإدخال.
تم إدخال العنوان. | المنطقة |
---|---|
1 Doctor Carlton B Goodlett Place, San Francisco, CA 94102 | الولايات المتحدة الأمريكية |
قرار عدم وجود المبنى الفرعي
في هذا المثال، لا يعرض البيان السمة addressComplete
، وبالتالي فإنّ المعرّف هو false
. لهذا السبب، فأنت تعلم أن عنصر عنوان واحدًا على الأقل
غير متوقع أو لم يتم حله أو مفقود.
{
"inputGranularity": "PREMISE",
"validationGranularity": "PREMISE",
"geocodeGranularity": "PREMISE",
"hasInferredComponents": true
}
يكشف طلب البحث address
ما يلي:
"missingComponentTypes": [
"subpremise"
]
بعد تقديم المزيد من الاستفسارات، توفّر بيانات USPS رمز dpvConfirmation
الخاص بـ
D
، ما يشير أيضًا إلى أنّ مكان العمل الفرعي غير متوفِّر.