این سند فرآیندی را برای ساخت یک سیستم بررسی آدرس برای مدیریت پاسخهای متنوع از API اعتبارسنجی آدرس شرح میدهد. این سند نحوه ساخت منطق شما برای استفاده صحیح از پاسخ، بررسی سایر سیگنالهای API و زمان و نحوه درخواست اطلاعات بیشتر از مشتریان شما را پوشش میدهد.
به طور کلی، پاسخ API روشهای زیر را برای مدیریت یک آدرس توسط سیستم شما تعیین میکند:
- - کیفیت آدرس پایین است. باید درخواست اطلاعات بیشتر کنید.
- تأیید —آدرس با کیفیت بالا است، اما نسبت به آدرس ورودی تغییراتی دارد. ممکن است از شما تأییدیه بخواهد.
- که آیا آدرس ارائه شده کیفیت بالایی دارد یا خیر. میتوانید آدرس ارائه شده را بپذیرید.
هدف کلیدی
این سند به شما کمک میکند تا سیستم خود را اصلاح کنید تا به بهترین شکل پاسخ API را تجزیه و تحلیل کرده و اقدامات بعدی را با آدرسهای ارائه شده تعیین کنید. شبهکد زیر یک جریان ممکن را نشان میدهد.
if (the API response indicates significant problems in the address)
FIX - prompt the user to fix the address
else if (the API response indicates less significant problems in the address)
CONFIRM - confirm with the user that the address is correct
else
ACCEPT - continue with the address returned by the API.
منطق دقیق به شرایط شما بستگی دارد؛ برای جزئیات بیشتر به راهنمای پیادهسازی مراجعه کنید. همچنین میتوانید از پیادهسازی متنباز ما از این منطق که در کتابخانه کامپوننتهای توسعهیافته قرار دارد، استفاده کنید.
مرور کلی گردش کار
جدول زیر دو اقدام برای سیستم شما را خلاصه میکند:
- گردش کاری که باید استفاده شود بر اساس رفتار اصلاح، تأیید، پذیرش است.
- اولین سیگنالهایی که باید از پاسخ بررسی شوند . سیگنالهای شرح داده شده در اینجا از ویژگی
verdictمیآیند و تنها سیگنالهای قابل بررسی نیستند ، اما یک شاخص اولیه از کیفیت آدرس را ارائه میدهند. هر نوع رفتار مربوط به بخشی در این سند است که سیگنالهای بیشتری را که ممکن است نیاز به بررسی داشته باشید، شرح میدهد.
| رفتار سیستم شما | |||
|---|---|---|---|
| آدرس را اصلاح کنید | پاسخ حاصل از
| ||
| آدرس را تأیید کنید | پاسخ حاصل از
| ||
| آدرس را | پاسخ API اعتبارسنجی آدرس، یک آدرس با کیفیت عالی را نشان میدهد.
| ||
راهنمای پیادهسازی
هنگام طراحی نحوه پاسخ سیستم شما به سیگنالهای اعتبارسنجی آدرس، توصیههای زیر میتواند به شما در ساخت یک مدل پاسخ مؤثرتر کمک کند. با این حال، اینها فقط توصیه هستند، بنابراین در نظر داشته باشید که پیادهسازی شما باید متناسب با مدل کسبوکارتان باشد.
| راهنمایی | جزئیات | |
|---|---|---|
| سطح ریسک | هنگام ایجاد تعادل بین درخواست اصلاحات و پذیرش آدرس وارد شده، سطح تحمل شرایط خود را در نظر بگیرید. | API اعتبارسنجی آدرس، سیگنالهای متنوعی را برمیگرداند که میتوانید آنها را با سطح ریسک خود ترکیب کنید تا فرآیند اعتبارسنجی خود را بهینه کنید. برای مثال، اگر یک آدرس دارای شماره خیابان تأیید نشده باشد، همچنان میتوانید آن را بپذیرید. از سوی دیگر، اگر عملیات تجاری شما نیاز به دقت آدرس بیشتری دارد، میتوانید از کاربر خود بخواهید که این کار را انجام دهد. برای مثالی که میتواند در هر دو دسته قرار گیرد، به بخش شماره خیابان تأیید نشده غیر آمریکایی در بخش پذیرش آدرس - مثالها مراجعه کنید. |
| آدرسها را بپذیرید | این یک روش خوب است که به سیستم خود اجازه دهید در صورت عدم پاسخ مشتری به درخواستها، ورودی اصلی را بپذیرد. | در این موارد، ممکن است مشتری آدرسی را وارد کرده باشد که در سیستم وجود ندارد، مثلاً برای ساختمان نوساز. |
اصلاح آدرس
وقتی نتایج به وضوح نشان میدهد که آدرس قابل تحویل نیست، آن را اصلاح کنید. سیستم شما میتواند از مشتری بخواهد اطلاعات لازم را ارائه دهد، پس از آن شما گردش کار خود را دوباره برای دریافت آدرس قابل تحویل ارسال میکنید.
سیگنالها را اصلاح کنید
API اعتبارسنجی آدرس تعدادی سیگنال ارائه میدهد تا به شما اطلاع دهد که آیا یک آدرس باید اصلاح شود یا خیر.
۱. جزئیات اعتبارسنجی و اجزای از دست رفته
این دو سیگنال بهترین نشانه برای وجود یک آدرس مشکلدار هستند:
- هر زمان که فیلد
validationGranularityOTHERباشد، سیستم شما باید سیگنالهای مؤلفه آدرس را بررسی کند تا اطلاعات بیشتری در مورد محل وقوع خطا و نحوه رفع آن کسب کند. - هر زمان که شیء
addressپسپردازششده، فیلدmissingComponentTypesرا برگرداند، سیستم شما باید آن کامپوننت را بررسی کند. کامپوننتهای گمشده همچنین یک آدرس را ناقص و غیرقابل تحویل میکنند.
۲. سیگنالهای دیگر
API اعتبارسنجی آدرس همچنین سیگنالهای دیگری را برای کمک به تشخیص مشکلات خاص ارائه میدهد:
| اجزای مشکوک | وقتی enum سطح تأیید برای یک کامپوننت UNCOMFIRMED_AND_SUSPICIOUS باشد، احتمالاً آن کامپوننت نادرست است. |
|---|---|
| جزء حل نشده | یک unresolvedToken بخشی از ورودی است که به عنوان بخش معتبری از یک آدرس شناخته نمیشود. |
۳. سیگنالهای آدرس ایالات متحده
فیلدهای خاصی که فقط برای آدرسهای ایالات متحده قابل استفاده هستند، سیگنال مفیدی ارائه میدهند که نشان میدهد آدرس قابل تحویل نیست و باید اصلاح شود. برای آدرسی که نیاز به اصلاح دارد، باید موارد زیر را مشاهده کنید:
dpvConfirmation | یا N ، یا D ، یا خالی. |
|---|
برای جزئیات بیشتر در مورد dpvConfirmation ، به بخش «مدیریت آدرسهای ایالات متحده» مراجعه کنید.
تأیید یک آدرس
شما زمانی یک آدرس را تأیید میکنید که حکم نشان دهد API اعتبارسنجی آدرس، اجزای آدرس را استنباط کرده یا تغییراتی در آنها ایجاد کرده تا یک آدرس معتبر تولید کند. در این موارد، شما یک آدرس قابل تحویل دارید، اما اطمینان بیشتری را ترجیح میدهید که آدرس حاصل، همان آدرس مورد نظر مشتری باشد.
برای ارائه درخواست صحیح به مشتری، منطق شما اجزای علامتگذاری شده توسط سرویس را شناسایی میکند تا مشخص شود کدام اقدام یا علامت API روی مؤلفه اعمال شده است، مانند inferred ، replaced یا spellCorrected . به AddressComponent در مرجع مراجعه کنید.
سیگنالها را تأیید کنید
API اعتبارسنجی آدرس تعدادی سیگنال ارائه میدهد تا به شما اطلاع دهد که آیا یک آدرس باید تأیید شود یا خیر.
۱. جزئیات اعتبارسنجی
validationGranularity با جزئیات ROUTE یا بهتر قابل قبول است، اما PREMISE یا SUBPREMISE سیگنال قویتری از قابلیت تحویل ارائه میدهند.
۲. سیگنالهای دیگر
هنگام تصمیمگیری برای تأیید ورود آدرس با مشتری، حکم موارد زیر را نیز برای تعیین مؤلفههای مورد بررسی ارائه میدهد:
| دادههای استنباطی | وقتی فیلد hasInferredComponents true باشد، میدانید که API اطلاعاتی را که از سایر اجزای آدرس جمعآوری کرده است، پر کرده است. |
|---|---|
| دادههای جایگزین شده | وقتی فیلد hasReplacedComponents برابر با true باشد، API دادههای وارد شده را با دادههایی که آدرس را معتبر میدانند، جایگزین میکند. |
۳. سیگنالهای آدرس ایالات متحده
فیلدهای خاصی که فقط برای آدرسهای ایالات متحده قابل استفاده هستند، نشان میدهند که منطق شما باید جزئیات را با مشتری تأیید کند. یکی از موارد زیر صدق میکند:
dpvConfirmation | S برای جزئیات بیشتر در مورد |
|---|---|
| پاسخ آدرس | حاوی فیلد missingComponentTypes با مقدار subpremise است. |
پذیرش آدرس
شما زمانی یک آدرس را میپذیرید که حکم، درجه بالایی از اطمینان را فراهم کند که آدرس قابل تحویل است و میتوان بدون تعامل بیشتر با مشتری در فرآیند پاییندستی از آن استفاده کرد.
سیگنالها را بپذیرید
API اعتبارسنجی آدرس تعدادی سیگنال ارائه میدهد تا به شما اطلاع دهد که آیا یک آدرس باید تأیید شود یا خیر.
۱. جزئیات اعتبارسنجی
validationGranularity در سطح PREMISE یا بهتر قابل قبول است، اما در برخی موارد، ROUTE همچنان نشاندهنده آدرس قابل تحویل است.
۲. سیگنالهای دیگر
یک حکم برای یک آدرس با کیفیت بالا باید موارد زیر را نیز ارائه دهد:
- هیچ دادهای جایگزین نشده است . در این مورد،
hasReplacedComponents: FALSE. - هیچ کامپوننت استنباطشدهای وجود ندارد . در این مورد،
hasInferredComponents: FALSE.
۳. سیگنالهای آدرس ایالات متحده
فیلدهای خاصی که فقط برای آدرسهای ایالات متحده قابل استفاده هستند، نشان دهنده آدرسی با کیفیت بالا هستند که میتوان به آن تحویل داد. برای یک آدرس قابل قبول در ایالات متحده، باید موارد زیر را مشاهده کنید:
dpvConfirmation | Y برای جزئیات بیشتر در مورد |
|---|