این سند فرآیندی را برای ساختن یک سیستم بررسی آدرس برای رسیدگی به انواع پاسخها از Address Validation API توضیح میدهد. نحوه ایجاد منطق خود برای استفاده صحیح از پاسخ، بررسی سیگنال های دیگر از API، و زمان و چگونگی درخواست اطلاعات بیشتر از مشتریان را پوشش می دهد.
به طور کلی پاسخ API راه های زیر را تعیین می کند که سیستم شما باید یک آدرس را مدیریت کند:
- Fix— آدرس کیفیت پایینی دارد. شما باید برای اطلاعات بیشتر درخواست کنید.
- تأیید - آدرس با کیفیت بالا است، اما تغییراتی نسبت به آدرس ورودی دارد. ممکن است از شما درخواست تأیید کنید.
- Accept را — آدرس با کیفیت است. می توانید آدرس ارائه شده را بپذیرید.
هدف کلیدی
این سند به شما کمک می کند تا سیستم خود را تغییر دهید تا پاسخ 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
می آیند و تنها سیگنال هایی نیستند که باید بررسی شوند، بلکه نشانگر اولیه کیفیت آدرس را ارائه می دهند. هر نوع رفتار مربوط به بخشی در این سند است که سیگنالهای بیشتری را که ممکن است نیاز به بررسی داشته باشید را توصیف میکند.
رفتار سیستم شما | |||
---|---|---|---|
آدرس رو درست کن | پاسخ
| ||
آدرس را تایید کنید | پاسخ از
| ||
Accept the address | پاسخ Address Validation API نشان دهنده یک آدرس با کیفیت عالی است.
|
راهنمای اجرا
هنگام طراحی نحوه پاسخگویی سیستم شما به سیگنالهای Address Validation API، توصیههای زیر میتواند به شما در ایجاد یک مدل پاسخ مؤثرتر کمک کند. با این حال، اینها فقط توصیه هایی هستند، بنابراین به خاطر داشته باشید که اجرای شما باید با مدل کسب و کار شما مطابقت داشته باشد.
راهنمایی | جزئیات | |
---|---|---|
سطح ریسک | هنگام ایجاد تعادل بین درخواست اصلاحات و پذیرش آدرس درج شده، سطح تحمل را برای موقعیت خود در نظر بگیرید. | Address Validation API سیگنالهای مختلفی را برمیگرداند که میتوانید با سطح ریسک خود برای بهینهسازی فرآیند اعتبارسنجی خود ترکیب کنید. به عنوان مثال، اگر آدرسی دارای شماره خیابان تایید نشده باشد، همچنان می توانید آن را بپذیرید. از سوی دیگر، اگر عملیات تجاری شما به دقت آدرس بیشتری نیاز دارد، ممکن است از کاربر خود درخواست کنید. برای مثالی که میتواند در هر یک از دستهها قرار گیرد، شماره خیابان تأیید نشده غیرآمریکایی را در آدرس پذیرش - نمونهها ببینید. |
آدرس ها را بپذیرید | اگر مشتری به درخواستها پاسخ ندهد، این روش خوبی است که به سیستم خود اجازه دهید ورودی اصلی را بپذیرد. | در این موارد، مشتری ممکن است آدرسی را وارد کرده باشد که در سیستم نیست، مثلاً برای ساخت و ساز جدید. |
بازخورد ارائه دهید | هنگامی که درخواست تأیید اعتبار آدرس را مجدداً صادر می کنید، می توانید درخواستی را به نقطه پایانی | این به Google اجازه میدهد بداند که در نهایت چگونه با پاسخ نهایی برخورد کردهاید. به آدرس های به روز شده رسیدگی کنید . |
یک آدرس را درست کنید
هنگامی که نتایج به وضوح نشان می دهد که آدرس قابل تحویل نیست، آدرسی را برطرف کنید. سپس سیستم شما میتواند از مشتری بخواهد اطلاعات لازم را ارائه کند، پس از آن شما گردش کار خود را مجدداً برای دریافت آدرس قابل تحویل صادر میکنید.
سیگنال ها را برطرف کنید
Address Validation API تعدادی سیگنال ارائه می دهد تا به شما اطلاع دهد که آیا یک آدرس باید اصلاح شود یا خیر.
1. اعتبار سنجی و اجزای گمشده
این دو سیگنال بهترین نشانه از یک آدرس مشکل ساز را ارائه می دهند:
- هر زمان که فیلد
validationGranularity
OTHER
باشد، سیستم شما باید سیگنال های جزء آدرس را بررسی کند تا درباره محل وقوع خطا و نحوه رفع آن اطلاعات بیشتری کسب کند. - هر زمان که شی
address
پس از پردازش، یک قسمتmissingComponentTypes
را برمی گرداند، سیستم شما باید آن جزء را بررسی کند. اجزای از دست رفته نیز آدرس را ناقص و غیر قابل تحویل نشان می دهد.
2. سیگنال های دیگر
Address Validation API همچنین سیگنال های دیگری را برای کمک به تشخیص مشکلات خاص ارائه می دهد:
اجزای مشکوک | وقتی شماره سطح تأیید برای یک مؤلفه UNCOMFIRMED_AND_SUSPICIOUS باشد، احتمالاً مؤلفه نادرست است. |
---|---|
جزء حل نشده | UnresolvedToken بخشی از ورودی است که به عنوان بخشی معتبر از یک آدرس شناخته نمی شود. |
3. سیگنال های آدرس ایالات متحده
برخی از فیلدها که فقط برای آدرس های ایالات متحده قابل اجرا هستند، سیگنال مفیدی را ارائه می دهند که نشانی قابل تحویل نیست و باید اصلاح شود. برای آدرسی که نیاز به تعمیر دارد، باید موارد زیر را ببینید:
dpvConfirmation | یا N ، D ، یا خالی. |
---|
برای جزئیات بیشتر در مورد dpvConfirmation
، به آدرس های ایالات متحده رسیدگی کنید .
یک آدرس را تایید کنید
زمانی که حکم نشان میدهد که Address Validation API استنباط کرده یا تغییراتی در اجزای آدرس به منظور تولید یک آدرس معتبر ایجاد کرده است، یک آدرس را تأیید میکنید. در این موارد، شما یک آدرس قابل تحویل دارید، اما ترجیح میدهید اطمینان بیشتری داشته باشید که نشانی بهدستآمده همان آدرسی است که مشتری در نظر گرفته است.
برای ارائه درخواست صحیح به مشتری، منطق شما مؤلفههای پرچمگذاریشده توسط سرویس را شناسایی میکند تا مشخص کند کدام عملکرد یا پرچم API روی مؤلفه اعمال میشود، مانند inferred
، replaced
یا spellCorrected
. AddressComponent را در مرجع ببینید.
سیگنال ها را تایید کنید
Address Validation API تعدادی سیگنال ارائه می دهد تا به شما اطلاع دهد که آیا یک آدرس باید تأیید شود.
1. اعتبار سنجی دانه بندی
validationGranularity
ROUTE
یا بهتر قابل قبول است، اما PREMISE یا SUBPREMISE سیگنال قوی تری از قابلیت تحویل ارائه می دهد.
2. سیگنال های دیگر
هنگام تصمیم گیری برای تأیید ورود آدرس با مشتری، حکم موارد زیر را نیز برای تعیین اینکه چه مؤلفه هایی باید بررسی شود ارائه می دهد:
داده های استنباط شده | وقتی فیلد hasInferredComponents true باشد، میدانید که API اطلاعاتی را که از سایر اجزای آدرس جمعآوری کرده بود، پر کرده است. |
---|---|
داده ها جایگزین شد | وقتی فیلد hasReplacedComponents true باشد، API دادههای وارد شده را با دادههایی که به نظر میرسد آدرس را معتبر میسازد جایگزین میکند. |
3. سیگنال های آدرس ایالات متحده
برخی از فیلدهای قابل اعمال فقط برای آدرس های ایالات متحده نشان می دهد که منطق شما باید جزئیات را با مشتری تأیید کند. هر یک از موارد زیر اعمال می شود:
dpvConfirmation | S برای جزئیات بیشتر در مورد |
---|---|
پاسخ آدرس | حاوی قسمت missingComponentType با مقدار subpremise است. |
یک آدرس بپذیرید
زمانی آدرسی را میپذیرید که حکم، اطمینان بالایی از قابلتحویل بودن آدرس ارائه میکند و میتواند بدون تعامل بیشتر با مشتری در فرآیند پاییندستی مورد استفاده قرار گیرد.
سیگنال ها را بپذیرید
Address Validation API تعدادی سیگنال ارائه می دهد تا به شما اطلاع دهد که آیا یک آدرس باید تأیید شود.
1. اعتبار سنجی دانه بندی
validationGranularity
PREMISE
یا بهتر قابل قبول است، اما در برخی موارد، ROUTE
همچنان یک آدرس قابل تحویل را نشان می دهد.
2. سیگنال های دیگر
یک حکم برای یک آدرس با کیفیت بالا باید موارد زیر را نیز ارائه دهد:
- داده ای جایگزین نشده است . در این مورد،
hasReplacedComponents: FALSE
. - هیچ جزء استنباط شده ای وجود ندارد . در این مورد،
hasInferredComponents: FALSE
.
3. سیگنال های آدرس ایالات متحده
فیلدهای خاصی که فقط برای آدرسهای ایالات متحده قابل اعمال هستند نشاندهنده یک آدرس با کیفیت بالا هستند که میتوان به آن تحویل داد. برای یک آدرس ایالات متحده قابل قبول، باید موارد زیر را ببینید:
dpvConfirmation | Y برای جزئیات بیشتر در مورد |
---|
این سند فرآیندی را برای ساختن یک سیستم بررسی آدرس برای رسیدگی به انواع پاسخها از Address Validation API توضیح میدهد. نحوه ایجاد منطق خود برای استفاده صحیح از پاسخ، بررسی سیگنال های دیگر از API، و زمان و چگونگی درخواست اطلاعات بیشتر از مشتریان را پوشش می دهد.
به طور کلی پاسخ API راه های زیر را تعیین می کند که سیستم شما باید یک آدرس را مدیریت کند:
- Fix— آدرس کیفیت پایینی دارد. شما باید برای اطلاعات بیشتر درخواست کنید.
- تأیید - آدرس با کیفیت بالا است، اما تغییراتی نسبت به آدرس ورودی دارد. ممکن است از شما درخواست تأیید کنید.
- Accept را — آدرس با کیفیت است. می توانید آدرس ارائه شده را بپذیرید.
هدف کلیدی
این سند به شما کمک می کند تا سیستم خود را تغییر دهید تا پاسخ 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
می آیند و تنها سیگنال هایی نیستند که باید بررسی شوند، بلکه نشانگر اولیه کیفیت آدرس را ارائه می دهند. هر نوع رفتار مربوط به بخشی در این سند است که سیگنالهای بیشتری را که ممکن است نیاز به بررسی داشته باشید را توصیف میکند.
رفتار سیستم شما | |||
---|---|---|---|
آدرس رو درست کن | پاسخ
| ||
آدرس را تایید کنید | پاسخ از
| ||
Accept the address | پاسخ Address Validation API نشان دهنده یک آدرس با کیفیت عالی است.
|
راهنمای اجرا
هنگام طراحی نحوه پاسخگویی سیستم شما به سیگنالهای Address Validation API، توصیههای زیر میتواند به شما در ایجاد یک مدل پاسخ مؤثرتر کمک کند. با این حال، اینها فقط توصیه هایی هستند، بنابراین به خاطر داشته باشید که اجرای شما باید با مدل کسب و کار شما مطابقت داشته باشد.
راهنمایی | جزئیات | |
---|---|---|
سطح ریسک | هنگام ایجاد تعادل بین درخواست اصلاحات و پذیرش آدرس درج شده، سطح تحمل را برای موقعیت خود در نظر بگیرید. | Address Validation API سیگنالهای مختلفی را برمیگرداند که میتوانید با سطح ریسک خود برای بهینهسازی فرآیند اعتبارسنجی خود ترکیب کنید. به عنوان مثال، اگر آدرسی دارای شماره خیابان تایید نشده باشد، همچنان می توانید آن را بپذیرید. از سوی دیگر، اگر عملیات تجاری شما به دقت آدرس بیشتری نیاز دارد، ممکن است از کاربر خود درخواست کنید. برای مثالی که میتواند در هر یک از دستهها قرار گیرد، شماره خیابان تأیید نشده غیرآمریکایی را در آدرس پذیرش - نمونهها ببینید. |
آدرس ها را بپذیرید | اگر مشتری به درخواستها پاسخ ندهد، این روش خوبی است که به سیستم خود اجازه دهید ورودی اصلی را بپذیرد. | در این موارد، مشتری ممکن است آدرسی را وارد کرده باشد که در سیستم نیست، مثلاً برای ساخت و ساز جدید. |
بازخورد ارائه دهید | هنگامی که درخواست تأیید اعتبار آدرس را مجدداً صادر می کنید، می توانید درخواستی را به نقطه پایانی | این به Google اجازه میدهد بداند که در نهایت چگونه با پاسخ نهایی برخورد کردهاید. به آدرس های به روز شده رسیدگی کنید . |
یک آدرس را درست کنید
هنگامی که نتایج به وضوح نشان می دهد که آدرس قابل تحویل نیست، آدرسی را برطرف کنید. سپس سیستم شما میتواند از مشتری بخواهد اطلاعات لازم را ارائه کند، پس از آن شما گردش کار خود را مجدداً برای دریافت آدرس قابل تحویل صادر میکنید.
سیگنال ها را برطرف کنید
Address Validation API تعدادی سیگنال ارائه می دهد تا به شما اطلاع دهد که آیا یک آدرس باید اصلاح شود یا خیر.
1. اعتبار سنجی و اجزای گمشده
این دو سیگنال بهترین نشانه از یک آدرس مشکل ساز را ارائه می دهند:
- هر زمان که فیلد
validationGranularity
OTHER
باشد، سیستم شما باید سیگنال های جزء آدرس را بررسی کند تا درباره محل وقوع خطا و نحوه رفع آن اطلاعات بیشتری کسب کند. - هر زمان که شی
address
پس از پردازش، یک قسمتmissingComponentTypes
را برمی گرداند، سیستم شما باید آن جزء را بررسی کند. اجزای از دست رفته نیز آدرس را ناقص و غیر قابل تحویل نشان می دهد.
2. سیگنال های دیگر
Address Validation API همچنین سیگنال های دیگری را برای کمک به تشخیص مشکلات خاص ارائه می دهد:
اجزای مشکوک | وقتی شماره سطح تأیید برای یک مؤلفه UNCOMFIRMED_AND_SUSPICIOUS باشد، احتمالاً مؤلفه نادرست است. |
---|---|
جزء حل نشده | UnresolvedToken بخشی از ورودی است که به عنوان بخشی معتبر از یک آدرس شناخته نمی شود. |
3. سیگنال های آدرس ایالات متحده
برخی از فیلدها که فقط برای آدرس های ایالات متحده قابل اجرا هستند، سیگنال مفیدی را ارائه می دهند که نشانی قابل تحویل نیست و باید اصلاح شود. برای آدرسی که نیاز به تعمیر دارد، باید موارد زیر را ببینید:
dpvConfirmation | N ، D ، یا خالی. |
---|
برای جزئیات بیشتر در مورد dpvConfirmation
، به آدرس های ایالات متحده رسیدگی کنید .
یک آدرس را تایید کنید
زمانی که حکم نشان میدهد که Address Validation API استنباط کرده یا تغییراتی در اجزای آدرس به منظور تولید یک آدرس معتبر ایجاد کرده است، یک آدرس را تأیید میکنید. در این موارد، شما یک آدرس قابل تحویل دارید، اما ترجیح میدهید اطمینان بیشتری داشته باشید که نشانی بهدستآمده همان آدرسی است که مشتری در نظر گرفته است.
برای ارائه درخواست صحیح به مشتری، منطق شما مؤلفههای پرچمگذاریشده توسط سرویس را شناسایی میکند تا مشخص کند کدام عملکرد یا پرچم API روی مؤلفه اعمال میشود، مانند inferred
، replaced
یا spellCorrected
. AddressComponent را در مرجع ببینید.
سیگنال ها را تایید کنید
Address Validation API تعدادی سیگنال ارائه می دهد تا به شما اطلاع دهد که آیا یک آدرس باید تأیید شود.
1. اعتبار سنجی دانه بندی
validationGranularity
ROUTE
یا بهتر قابل قبول است، اما PREMISE یا SUBPREMISE سیگنال قوی تری از قابلیت تحویل ارائه می دهد.
2. سیگنال های دیگر
هنگام تصمیم گیری برای تأیید ورود آدرس با مشتری، حکم موارد زیر را نیز برای تعیین اینکه چه مؤلفه هایی باید بررسی شود ارائه می دهد:
داده های استنباط شده | وقتی فیلد hasInferredComponents true باشد، میدانید که API اطلاعاتی را که از سایر اجزای آدرس جمعآوری کرده بود، پر کرده است. |
---|---|
داده ها جایگزین شد | وقتی فیلد hasReplacedComponents true باشد، API دادههای وارد شده را با دادههایی که به نظر میرسد آدرس را معتبر میسازد جایگزین میکند. |
3. سیگنال های آدرس ایالات متحده
برخی از فیلدهای قابل اعمال فقط برای آدرس های ایالات متحده نشان می دهد که منطق شما باید جزئیات را با مشتری تأیید کند. هر یک از موارد زیر اعمال می شود:
dpvConfirmation | S برای جزئیات بیشتر در مورد |
---|---|
پاسخ آدرس | حاوی قسمت missingComponentType با مقدار subpremise است. |
یک آدرس بپذیرید
زمانی آدرسی را میپذیرید که حکم، اطمینان بالایی از قابلتحویل بودن آدرس ارائه میکند و میتواند بدون تعامل بیشتر با مشتری در فرآیند پاییندستی مورد استفاده قرار گیرد.
سیگنال ها را بپذیرید
Address Validation API تعدادی سیگنال ارائه می دهد تا به شما اطلاع دهد که آیا یک آدرس باید تأیید شود.
1. اعتبار سنجی دانه بندی
validationGranularity
PREMISE
یا بهتر قابل قبول است، اما در برخی موارد، ROUTE
همچنان یک آدرس قابل تحویل را نشان می دهد.
2. سیگنال های دیگر
یک حکم برای یک آدرس با کیفیت بالا باید موارد زیر را نیز ارائه دهد:
- داده ای جایگزین نشده است . در این مورد،
hasReplacedComponents: FALSE
. - هیچ جزء استنباط شده ای وجود ندارد . در این مورد،
hasInferredComponents: FALSE
.
3. سیگنال های آدرس ایالات متحده
فیلدهای خاصی که فقط برای آدرسهای ایالات متحده قابل اعمال هستند نشاندهنده یک آدرس با کیفیت بالا هستند که میتوان به آن تحویل داد. برای یک آدرس ایالات متحده قابل قبول، باید موارد زیر را ببینید:
dpvConfirmation | Y برای جزئیات بیشتر در مورد |
---|