با مجموعهها، منظم بمانید
ذخیره و طبقهبندی محتوا براساس اولویتهای شما.
این سند تعدادی از سناریوهای دنیای واقعی را توصیف می‌کند که در آن Address Validation API سیگنال‌های پاسخی را ارائه می‌دهد که ممکن است رفتار اصلاحی سیستم شما را تضمین کند. نمونه گردش کار را در Build your validation logic for context ببینید.
مثال های رایج: رفع
این بخش نمونه‌های رایجی را توضیح می‌دهد که در آن Address Validation API سیگنال‌های پاسخی را ارائه می‌کند که اطلاعات آدرس با کیفیت پایین‌تری را نشان می‌دهد.
شهر و کد پستی موجود نیست
این مثال یک ورودی را نشان می‌دهد که فقط آدرس خیابان دارد، بدون شهر یا کد پستی.
possibleNextAction نشانه اولیه ای را ارائه می دهد که نشانی ممکن است قابل تحویل نباشد. سایر مؤلفه های برجسته شده نیز از این امکان پشتیبانی می کنند، بنابراین می توانید برای کسب اطلاعات بیشتر addressComponents جستجو کنید:
Address Validation API فقط کشور (ایالات متحده) را به عنوان CONFIRMED برمی گرداند. همه اجزای آدرس دیگر را به‌عنوان UNCONFIRMED_BUT_PLAUSIBLE ، با برخی حذفیات مهم در داده‌ها، مانند محل و کد پستی، برمی‌گرداند.
یک بار دیگر، possibleNextAction یک نشانه اولیه را ارائه می دهد که نشانی ممکن است قابل تحویل نباشد. علاوه بر این، validationGranularityROUTE است، که نشان‌دهنده تطابق با خیابان است، اما اطلاعات کافی برای رسیدن به محل وجود ندارد. علاوه بر این، ویژگی addressComplete در حکم وجود ندارد و بنابراین false است. یک پرس و جو بیشتر از شی address یک نوع مؤلفه گمشده را نشان می دهد:
"missingComponentTypes": [
"street_number"
]
مثال‌های حاشیه‌ای: تعمیر
در برخی شرایط، اینکه آیا آدرسی را تصحیح، تأیید یا قبول می کنید، به سناریوی تجاری خاص شما بستگی دارد. مثال‌های زیر سناریوهایی را نشان می‌دهند که ممکن است به شدت در یک دسته تعمیر قرار نگیرند.
شماره خیابان تایید نشده
در این سناریو، Address Validation API نمی تواند شماره خیابان ارائه شده را تأیید کند، اما نشان می دهد که آدرس کامل است.
ارزش بررسی ترکیبی از یک ریزه کاری اعتبارسنجی را فقط برای تقریب در سطح مقدماتی همراه با مؤلفه های تأیید نشده دارد. یک پرس و جو از ویژگی addressComponentscomponentType تایید نشده زیر را نشان می دهد:
در اینجا، confirmation_levelstreet_number روی UNCONFIRMED_BUT_PLAUSIBLE تنظیم شده است. تأیید نشده به این معنی است که سرویس نمی تواند با شماره خیابان 84 در مجموعه داده خود مطابقت داشته باشد، و قابل قبول به این معنی است که داده های مؤلفه هنوز می توانند معتبر باشند.
فرض فرعی وجود ندارد
این سناریو آدرسی را توصیف می‌کند که فقط یک فرض فرعی مانند یک آپارتمان یا شماره بخش وجود ندارد. در غیر این صورت، Address Validation API می تواند آدرس را به طور کامل تأیید کند. همانطور که در مواردی که هر جزء آدرسی وجود ندارد، addressCompletefalse است و بنابراین در بازرسی دستی حکم وجود ندارد.
برای مثال، فرض کنید مشتری یک آدرس معتبر برای دفتر ارزیاب شهر سانفرانسیسکو وارد کرده است، اما شماره اتاق را از ورودی نادیده می گیرد.
آدرس وارد شد
منطقه
1 Doctor Carlton B Goodlett Place، سانفرانسیسکو، CA 94102
ایالات متحده آمریکا
حکم برای از دست دادن فرض فرعی
در این مثال، حکم خاصیت addressComplete را نمایش نمی‌دهد، بنابراین false است. به همین دلیل، می دانید که حداقل یک عنصر آدرس غیرمنتظره، حل نشده یا گم شده است.
تاریخ آخرین بهروزرسانی 2025-08-29 بهوقت ساعت هماهنگ جهانی.
[[["درک آسان","easyToUnderstand","thumb-up"],["مشکلم را برطرف کرد","solvedMyProblem","thumb-up"],["غیره","otherUp","thumb-up"]],[["اطلاعاتی که نیاز دارم وجود ندارد","missingTheInformationINeed","thumb-down"],["بیشازحد پیچیده/ مراحل بسیار زیاد","tooComplicatedTooManySteps","thumb-down"],["قدیمی","outOfDate","thumb-down"],["مشکل ترجمه","translationIssue","thumb-down"],["مشکل کد / نمونهها","samplesCodeIssue","thumb-down"],["غیره","otherDown","thumb-down"]],["تاریخ آخرین بهروزرسانی 2025-08-29 بهوقت ساعت هماهنگ جهانی."],[[["\u003cp\u003eThis document provides real-world examples of when the Address Validation API signals that an address needs to be fixed.\u003c/p\u003e\n"],["\u003cp\u003eThe API provides signals such as \u003ccode\u003evalidationGranularity\u003c/code\u003e, \u003ccode\u003econfirmationLevel\u003c/code\u003e, and \u003ccode\u003emissingComponentTypes\u003c/code\u003e to indicate potential issues with an address.\u003c/p\u003e\n"],["\u003cp\u003eCommon fix scenarios include missing city/postal code, missing street number, unconfirmed street number, and missing subpremise.\u003c/p\u003e\n"],["\u003cp\u003eThe recommended action for these scenarios is typically to prompt the user for the missing or unconfirmed information.\u003c/p\u003e\n"],["\u003cp\u003eWhether to fix, confirm, or accept an address can depend on specific business needs and risk tolerance.\u003c/p\u003e\n"]]],["The Address Validation API flags addresses needing correction through response signals. Common issues include missing city/postal codes or street numbers, where the API returns unconfirmed components and suggests user prompts for missing data. Edge cases, like unconfirmed street numbers or missing subpremises, trigger `UNCONFIRMED_BUT_PLAUSIBLE` or missing `addressComplete`, respectively. These scenarios might require user confirmation, depending on delivery risk. Missing subpremises are specifically flagged in the US and prompt a request to the user.\n"],null,["This document describes a number of real-world scenarios where the\nAddress Validation API provides response signals that might warrant a *fix* behavior\nfrom your system. See\n[Example workflows](/maps/documentation/address-validation/build-validation-logic#example-workflows) in\n**Build your validation logic** for context.\n| **Note:** The examples here are illustrative, but don't cover all scenarios.\n\nCommon examples: fix\n\nThis section describes common examples where the Address Validation API\nprovides response signals indicating lower quality address information.\n\nMissing city and postal code\n\nThis example illustrates an entry having only the street address, with no city\nor postal code.\n\n| Address entered | Region |\n|-------------------|--------|\n| 21 45 40th street | USA |\n\nVerdict for missing city and postal code\n\nThe example below emphasizes the important signals from the response. \n\n {\n \"inputGranularity\": \"PREMISE\",\n \"validationGranularity\": \"OTHER\",\n \"geocodeGranularity\": \"OTHER\",\n \"hasUnconfirmedComponents\": true,\n \"possibleNextAction\": \"FIX\"\n }\n\nThe `possibleNextAction` provides an initial indication that the address might\nnot be deliverable. The other highlighted components also support this\npossibility, so you can query the `addressComponents` to learn more: \n\n {\n \"componentName\": {\n \"text\": \"21\",\n \"languageCode\": \"en\"\n },\n \"componentType\": \"street_number\",\n \"confirmationLevel\": \"UNCONFIRMED_BUT_PLAUSIBLE\"\n },\n {\n \"componentName\": {\n \"text\": \"45 40th street\",\n \"languageCode\": \"en\"\n },\n \"componentType\": \"route\",\n \"confirmationLevel\": \"UNCONFIRMED_BUT_PLAUSIBLE\"\n },\n {\n \"componentName\": {\n \"text\": \"United States\",\n \"languageCode\": \"en\"\n },\n \"componentType\": \"country\",\n \"confirmationLevel\": \"CONFIRMED\"\n }\n\nThe Address Validation API returns only the country (United States) as `CONFIRMED`.\nIt returns all other address components as `UNCONFIRMED_BUT_PLAUSIBLE`, with\nsome important omissions to the data, such as locality and postal code.\n| **Action:** For this address, you might prompt your user for the missing information.\n\nMissing street number\n\nThis example shows a missing street number.\n\n| Address entered | Region |\n|-----------------------------------------|--------|\n| Buckingham Palace Road, SW1W 9TQ London | UK |\n\nVerdict for missing street number \n\n {\n \"inputGranularity\": \"PREMISE_PROXIMITY\",\n \"validationGranularity\": \"ROUTE\",\n \"geocodeGranularity\": \"ROUTE\",\n \"possibleNextAction\": \"FIX\"\n }\n\nOnce again, the `possibleNextAction` provides an initial indication that the\naddress might not be deliverable. Furthermore, the `validationGranularity` is\n`ROUTE`, which indicates a match to the street, but not enough information to\nget to the premise. Additionally, the `addressComplete` property is missing from\nthe verdict, and therefore it is `false`. A further query of the `address`\nobject reveals a missing component type: \n\n \"missingComponentTypes\": [\n \"street_number\"\n ]\n\n| **Action:** For this address, you might prompt your user for the missing information.\n\nEdge-case examples: fix\n\nIn some situations, whether you fix, confirm, or accept an address\ndepends on your particular business scenario. The examples below illustrate\nscenarios that might not strictly fall into a fix category.\n\nUnconfirmed street number\n\nIn this scenario, the Address Validation API cannot confirm the supplied street\nnumber, yet it indicates that the address is complete.\n\n| Address entered | Region |\n|---------------------------------------------|--------|\n| 84 Buckingham Palace Road, SW1W 9TQ, London | UK |\n\nVerdict for unconfirmed street number\n\nThe example below emphasizes the important signals. \n\n {\n \"inputGranularity\": \"PREMISE\",\n \"validationGranularity\": \"PREMISE_PROXIMITY\",\n \"geocodeGranularity\": \"PREMISE_PROXIMITY\",\n \"addressComplete\" : true,\n \"hasUnconfirmedComponents\": true,\n \"possibleNextAction\": \"ACCEPT\"\n }\n\nIt's worth investigating the combination of a validation granularity only to\npremise-level approximation along with unconfirmed components. A query of the\n`addressComponents` property shows the following unconfirmed `componentType`: \n\n {\n \"componentName\": {\n \"text\": \"84\",\n \"languageCode\": \"en\"\n },\n \"componentType\": \"street_number\",\n \"confirmationLevel\": \"UNCONFIRMED_BUT_PLAUSIBLE\"\n }\n\nHere, the `confirmation_level` of the `street_number` is set to\n`UNCONFIRMED_BUT_PLAUSIBLE`. *Unconfirmed* means that the service cannot match\nthe street number of 84 in its dataset, and *plausible* means that the\ncomponent data could still be valid.\n| **Action:** You can either accept the input as entered, or confirm with the customer to determine if the street number entered was intended or an error. Your response depends on the level of risk associated with your delivery. See [Implementation guidance](/maps/documentation/address-validation/build-validation-logic#implementation_guidance) in **Build your validation logic**.\n\nMissing subpremise\n\nThis scenario describes an address that is only missing a subpremise, such as an\napartment or department number. Otherwise, the Address Validation API can fully\nvalidate the address. As is the case when any address component is missing, the\nthe `addressComplete` is `false` and therefore not present on manual inspection\nof the verdict.\n| **Note:** In some countries, the Address Validation API cannot detect a missing subpremise; while in the US, a missing `SUB_PREMISE` indicates a non-deliverable address.\n\nTo illustrate, suppose a customer enters a valid address for the San Francisco\ncity assessor's office, but misses the room number from the input.\n\n| Address entered | Region |\n|------------------------------------------------------------|--------|\n| 1 Doctor Carlton B Goodlett Place, San Francisco, CA 94102 | USA |\n\nVerdict for missing subpremise\n\nIn this example, the verdict does not display the `addressComplete` property, so\ntherefore it is `false`. Because of this, you know that at least one address\nelement is unexpected, unresolved, or missing. \n\n {\n \"inputGranularity\": \"PREMISE\",\n \"validationGranularity\": \"PREMISE\",\n \"geocodeGranularity\": \"PREMISE\",\n \"hasInferredComponents\": true,\n \"possibleNextAction\": \"CONFIRM_ADD_SUBPREMISES\"\n }\n\nAn `address` query reveals the following: \n\n \"missingComponentTypes\": [\n \"subpremise\"\n ]\n\nUpon further inquiry, the USPS data provides a `dpvConfirmation` code of\n`D`, which also indicates a missing subpremise.\n| **Action:** For this address, you might prompt your user for the missing information."]]
