راهنمای راه‌حل اعتبارسنجی نشانی

هدف اصلی

«اعتبارسنجی نشانی» برای موارد استفاده مختلفی ارزش ارائه می‌دهد و ملاحظات کلیدی‌ای فراتر از کیفیت خام نتایج آزمایشی وجود دارد که پیشنهاد می‌کنیم آن‌ها را بررسی کنید. برای مثال: نمای کلی محصولات سازگار در جریان کاربر مانند تکمیل خودکار جا و Maps، دردسترس بودن منطقه‌ای، و اعتماد و قابلیت اطمینان سازمانی.

وقتی به مرحله ارزیابی Address Validation API رسیدید، در اینجا چند رهنمود آورده‌ایم که توصیه می‌کنیم به‌عنوان بخشی از آزمایش خود از آن‌ها استفاده کنید.

اهداف این آزمایش عبارت‌اند از:

1. مطمئن شوید Address Validation API برای مورد استفاده شما مناسب است.
2. بررسی کنید که Address Validation API چگونه الزامات راه‌حل‌های شما را برآورده می‌کند، ازجمله:
   • شناسایی نشانی‌های با کیفیت خوب.
   • هشدار دادن برای رسیدگی به ورودی‌هایی که کیفیت پایینی دارند.
   • اصلاح داده‌های نشانی، ازجمله استنتاج‌ها، جایگزینی‌ها، و اصلاحات املایی.
   • ارائه نشانی قالب‌بندی‌شده برای ارسال کالا.
   • هشدار دادن درباره داده‌های فرعی مفقود یا نادرست (فقط ایالات متحده).
3. مطمئن شوید که با پیاده‌سازی میانای برنامه‌سازی کاربردی، مزیت قابل‌اندازه‌گیری دریافت خواهید کرد.

پس‌از انجام آزمایش، می‌توانید به سؤالات بالا پاسخ دهید و تعیین کنید که آیا میانای برنامه‌سازی کاربردی برای کسب‌وکارتان مناسب است یا نه.

آماده‌سازی داده‌ها

آزمایش شما باید دربرابر نمونه‌ای از داده‌های نشانی موجودتان انجام شود. داده‌ها را برای آزمایش دست‌چین نکنید، بلکه نمونه‌های تصادفی را انتخاب کنید که معرف مناطق جغرافیایی‌ای باشند که در آن‌ها فعالیت می‌کنید. این یعنی اگر هم در ایالات متحده و هم در پادشاهی متحد فعالیت می‌کنید، اما ۷۰٪ کسب‌وکارتان در پادشاهی متحد و ۳۰٪ آن در ایالات متحده انجام می‌شود، نمونه باید این تقسیم‌بندی را منعکس کند.

از نشانی‌های نقطه ثبت استفاده کنید. برای مثال، اگر قصد دارید اعتبارسنجی نشانی را در فرایند تسویه‌حساب تجارت الکترونیک خود پیاده‌سازی کنید، از نشانی‌هایی استفاده کنید که مشتریان در فرم وارد کرده‌اند، قبل‌از اینکه هرگونه پردازش موجودی که ممکن است با پیاده‌سازی Address Validation API جایگزین شود، انجام شده باشد.

یک اندازه نمونه حدود ۵۰۰۰ تا ۱۰۰۰۰ رکورد برای آزمایش آماده کنید.

فراخوانی میانای برنامه‌سازی کاربردی

پیش‌نیاز بخش: آشنایی با نحوه ارسال درخواست اعتبارسنجی نشانی.

وقتی داده‌ها را آماده کردید، باید هر سابقه نشانی را درمقابل میانای برنامه‌سازی کاربردی اجرا کنید.

برای راهنمایی درباره نحوه فراخوانی میانای برنامه‌سازی کاربردی، به اسناد Address Validation API مراجعه کنید. همچنین مقاله‌ای داریم که روال‌های مطلوب برای استفاده از Address Validation API برای پردازش نشانی‌ها در حجم بالا را شرح می‌دهد.

نتیجه این مرحله باید خروجی داده از API برای هر رکورد نشانی باشد. سپس می‌توانید نتایج را تجزیه‌وتحلیل کنید تا مناسب بودن میانای برنامه‌سازی کاربردی را برای مورد استفاده‌تان تعیین کنید. اینکه از صفحه‌گسترده، پایگاه داده، یا ابزار دیگری استفاده کنید به خودتان بستگی دارد.

مرور نتایج

پیش‌نیاز بخش: آشنایی با نحوه رسیدگی به پاسخ اعتبارسنجی، به‌ویژه مفهوم «اصلاح»، «تأیید»، و «پذیرش».

در این بخش، سناریوهای خروجی را که ممکن است برای ارزیابی تناسب راه‌حل تحلیل کنید، مورد بحث قرار خواهیم داد.

نمای کلی فیلدهای کلیدی API که در این سند مورد بحث قرار گرفته است

داده‌های پاسخ	این چیست؟	نحوه ارزیابی	چگونه کمک می‌کند؟
verdict.inputGranularity	دقت ورودی نشانی را شرح می‌دهد.	SUB_PREMISE PREMISE PREMISE_PROXIMITY مسدود کردن ROUTE موارد دیگر	به شما امکان می‌دهد تعیین کنید آیا نشانی ورودی داده‌های کافی برای معتبر بودن احتمالی دارد یا نه.
verdict.validationGranularity	اعتبارسنجی کلی برونداد نشانی را شرح می‌دهد.	SUB_PREMISE PREMISE PREMISE_PROXIMITY مسدود کردن ROUTE موارد دیگر	به شما امکان می‌دهد کیفیت کلی نشانی را در برونداد از میانای برنامه‌سازی کاربردی تعیین کنید.
verdict.hasInferredComponents	اگر میانای برنامه‌سازی کاربردی مؤلفه‌ای را استنباط کرده باشد، علامت می‌دهد.	درست/نادرست	میانای برنامه‌سازی کاربردی می‌تواند مؤلفه‌های جاافتاده را در جایی که می‌تواند داده‌ها را استنباط کند اضافه کند. برای مثال، کد ایالت وجود ندارد.
verdict.hasReplacedComponents	نشان می‌دهد که آیا API قطعه‌ای را جایگزین کرده است یا نه.	درست/نادرست	در برخی سناریوها، میانای برنامه‌سازی کاربردی می‌تواند مؤلفه‌های نادرست را با داده‌های صحیح جایگزین کند.
verdict.addressComplete	نشان می‌دهد که نشانی کامل است یا نه.	درست/نادرست	اگر API تشخیص دهد که نشانی خروجی همه مؤلفه‌های لازم را دارد، این مقدار درست خواهد بود.
address.missingComponentTypes	سیگنال هشدار درصورت وجود نداشتن مؤلفه‌های نشانی.	برای مقادیر، جدول دو را ببینید.	بخش‌های جاافتاده نشانی ناقص را برجسته کنید.

مرور نشانی‌های معتبر

داده‌های برگشتی از میانای برنامه‌سازی کاربردی را مرتب کنید تا مجموعه نشانی‌هایی را که سیستمتان به‌عنوان معتبر می‌پذیرد تعیین کنید. نشان‌های کلیدی که باید از API جستجو کنید عبارتند از:

• verdict.validationGranularity حاوی PREMISE یا بهتر است.
• verdict.addressComplete true است.
• هیچ قطعه استنباط‌شده یا جایگزین‌شده‌ای وجود ندارد.

برای اطلاعات بیشتر، پذیرفتن نشانی را ببینید.

خروجی این تمرین باید زیرمجموعه‌ای از داده‌های نشانی باشد که سیستم شما آن را به‌عنوان نشانی معتبر می‌پذیرد. در این مرحله، می‌توانید موارد زیر را تعیین کنید:

• آیا نرخ درصد پذیرش قابل‌قبول است؟
• اگر از گردش کار اعتبارسنجی نشانی موجود استفاده می‌کنید، آیا نرخ پذیرش برابر یا بهتر است؟

مثال: نشانی معتبر

نشانی واردشده	منطقه
76 Buckingham Palace Road, London SW1W 9TQ	بریتانیا

رأی

{
  "inputGranularity": "PREMISE",
  "validationGranularity": "PREMISE",
  "geocodeGranularity": "PREMISE",
  "addressComplete": true
}

بازبینی نشانی‌های نامعتبر

این مرحله فرصتی است برای بازبینی دستی برخی‌از داده‌های نشانی که به‌عنوان نامعتبر علامت‌گذاری شده‌اند و بررسی اینکه آیا بدون استفاده از Address Validation API، آن نشانی نامعتبر می‌تواند باعث مشکلات پایین‌دستی شود یا نه.

داده‌های برگردانده‌شده از میانای برنامه‌سازی کاربردی را مرتب کنید تا مجموعه نشانی‌هایی را که سیستم شما به‌عنوان نامعتبر علامت‌گذاری می‌کند تعیین کنید. نشان‌های کلیدی که باید از API جستجو کنید عبارتند از:

• verdict.validationGranularity بسته به سطح ریسک شما روی OTHER یا ROUTE تنظیم شده است.
• verdict.addressComplete false است.

برای اطلاعات بیشتر، اصلاح نشانی را ببینید.

خروجی این تمرین باید زیرمجموعه‌ای از داده‌های نشانی باشد که توسط سیستم شما به‌عنوان نامعتبر علامت‌گذاری می‌شود. در این مرحله، می‌توانید تعیین کنید که آیا نرخ درصد نامعتبر قابل‌قبول است یا نه.

توجه به این نکته مهم است که علامت‌گذاری نشانی‌ها به‌عنوان نامعتبر بخش اصلی عملکرد Address Validation API است و نرخ بالای نشانی‌های علامت‌گذاری‌شده به‌عنوان نامعتبر لزوماً نشان‌دهنده عملکرد ضعیف API نیست. این میانای برنامه‌سازی کاربردی اطلاعاتی به شما می‌دهد که نشان می‌دهد مشکلی در نشانی وجود دارد و این امر می‌تواند با شناسایی خطاها در مراحل اولیه و پیش‌از ایجاد مشکلات در مراحل بعدی، کارایی گردش کار شما را افزایش دهد.

مثال: نشانی نامعتبر

نشانی واردشده	منطقه
21 45 40th street	ایالات متحده آمریکا

رأی

{
  "inputGranularity": "PREMISE",
  "validationGranularity": "OTHER",
  "geocodeGranularity": "OTHER",
  "hasUnconfirmedComponents": true
}

بازبینی قطعات مفقود یا تأییدنشده

در این مرحله، قطعات مفقودشده یا تأییدنشده نیز می‌توانند بررسی شوند. این بخشی از شیء نشانی در بازگشت است. این دو فیلد عبارت‌اند از missingComponentTypes و unconfirmedComponentTypes.

از این فیلدها برای کمک به تشخیص دلیل علامت‌گذاری نشانی به‌عنوان نامعتبر توسط میانای برنامه‌سازی کاربردی استفاده کنید و اطلاعات صحیح را برای نشانی جمع‌آوری کنید تا با بازخورد دادن فیلد(های) خاصی که نادرست هستند به نقطه جمع‌آوری داده، معتبر شود. این یکی از روش‌هایی است که API با ارائه اطلاعات خاص درباره کیفیت داده‌هایتان، ارزش ایجاد می‌کند.

مثال: قطعه مفقودشده و تأییدنشده

نشانی واردشده	منطقه
Fake St, New York, NY 10011	ایالات متحده آمریکا

رأی

{
     "inputGranularity": "ROUTE",
     "validationGranularity": "OTHER",
     "geocodeGranularity": "OTHER",
     "hasUnconfirmedComponents": true
}

قطعات مفقود و تأییدنشده

"missingComponentTypes": [
    "street_number"
],
"unconfirmedComponentTypes": [
    "route"
]

بازبینی نشانی‌های دارای اصلاحیه

Address Validation API می‌تواند داده‌های ورودی را اصلاح کند، ورودی نشانی احتمالاً نامعتبر را دریافت کند، و داده‌های نشانی معتبر را خروجی دهد. این یکی از روش‌هایی است که API ارزش‌افزوده ایجاد می‌کند و مهم است که این موضوع به‌عنوان بخشی از آزمایش ثبت شود.

نشان‌های کلیدی که باید به‌دنبال آن‌ها باشید عبارتند از:

• ‫inferred، replaced، یا spellCorrected روی true در هرکدام از addressComponents تنظیم شده باشد.
• ‫verdict.hasInferredComponents یا verdict.hasReplacedComponents روی true تنظیم شده است.

برای اطلاعات بیشتر، تأیید نشانی را ببینید.

خروجی این تمرین باید زیرمجموعه‌ای از داده‌های نشانی باشد که توسط API اصلاح شده است.

بخشی از این داده‌ها را می‌توان به‌صورت دستی بازبینی کرد تا مشخص شود که آیا API اصلاحاتی در داده‌های شما ایجاد می‌کند که باعث کاهش اصطکاک در گردش کار پایین‌دستی شما شود یا نه.

مثال: نشانی با تصحیح

نشانی واردشده	منطقه
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 را می‌توان برای مشاهده این داده‌ها و تعیین اینکه آیا به گردش کار شما ارزش می‌افزاید یا نه، بررسی کرد.

مثال: نشانی استانداردشده USPS

"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 برای گردش کار شما ارزش‌آفرین خواهد بود یا نه خواهید داشت.

مطالعه بیشتر پیشنهادی:

• اسناد توسعه‌دهنده Address Validation API
• استفاده از Address Validation API برای پردازش نشانی‌ها در حجم بالا
• اعتبارسنجی نشانی برای تسویه‌حساب تجارت الکترونیک

همیاران

هنریک والو | مهندس DevX