تنظيم صفحاتك في مجموعات
يمكنك حفظ المحتوى وتصنيفه حسب إعداداتك المفضّلة.
يوضّح هذا المستند عددًا من السيناريوهات الواقعية التي تقدّم فيها واجهة Address Validation API إشارات استجابة تضمن سلوك قبول من نظامك. اطّلِع على
أمثلة على سير العمل في
إنشاء منطق التحقّق من الصحة للحصول على السياق.
مثال شائع: قبول
يوضّح هذا السيناريو عنوانًا سيقبله نظامك إذا أدخله أحد العملاء.
وعند دمجها معًا، تشير هذه الإشارات إلى عنوان عالي الجودة.
أمثلة على الحالات الحدّية: قبول
تغطّي الأمثلة التالية الحالات التي يشير فيها الرمز verdict إلى مشاكل في جودة العنوان تستدعي إجراء المزيد من التحقيق. توضّح هذه الأمثلة أيضًا كيف يمكن أن تنتقل منطقك من نتيجة التحقّق إلى مكوّنات العنوان للحصول على صورة أكثر اكتمالاً من أجل تحسين منطق نظامك.
رقم شارع غير مؤكَّد خارج الولايات المتحدة
يوضّح هذا المثال إدخال عنوان إيطالي يتضمّن جميع مكوّنات العنوان
بدون أي مكوّنات مستنتَجة أو مستبدَلة. ومع ذلك، فإنّ
validationGranularity هو ROUTE.
تم إدخال العنوان
المنطقة
Via Fonte Grugnale, 14 unit 2, 66054 Vasto CH, Italia
يوضّح هذا المثال إدخال عنوان في الولايات المتحدة مع توفّر جميع مكوّنات العنوان، بدون أي مكوّنات مستنتَجة أو مستبدَلة. ومع ذلك، فإنّ
validationGranularity هو PREMISE_PROXIMITY.
بيانات غير مكتملة من خدمة البريد الأمريكية (USPS) لعنوان تم تأكيده
يوضّح هذا المثال إدخال عنوان في الولايات المتحدة مع تأكيد جميع مكوّنات العنوان، بدون أي مكوّنات مستنتَجة أو مستبدَلة، وبدقة validationGranularity تبلغ PREMISE. ومع ذلك، لم تتم تعبئة uspsData بالكامل، ولا يحتوي على قيمة dpvConfirmation.
تم إدخال العنوان
المنطقة
155 Via Condado Way, Palm Beach Gardens, FL 33418-1703
الولايات المتحدة
حالة عنوان مؤكَّد يتضمّن بيانات غير مكتملة من خدمة البريد الأمريكية
تاريخ التعديل الأخير: 2025-08-31 (حسب التوقيت العالمي المتفَّق عليه)
[[["يسهُل فهم المحتوى.","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-31 (حسب التوقيت العالمي المتفَّق عليه)"],[[["\u003cp\u003eThe Address Validation API provides signals to determine if an address should be accepted by your system, even with minor uncertainties.\u003c/p\u003e\n"],["\u003cp\u003eAddresses with \u003ccode\u003evalidationGranularity\u003c/code\u003e of \u003ccode\u003ePREMISE\u003c/code\u003e and no unconfirmed/inferred/replaced components are generally safe to accept.\u003c/p\u003e\n"],["\u003cp\u003eAddresses with \u003ccode\u003eUNCONFIRMED_BUT_PLAUSIBLE\u003c/code\u003e street numbers can be accepted, but consider prompting the customer for confirmation for higher confidence.\u003c/p\u003e\n"],["\u003cp\u003eUS addresses with \u003ccode\u003edpvConfirmation\u003c/code\u003e of 'N' might require customer confirmation or correction, depending on your system's confidence requirements.\u003c/p\u003e\n"],["\u003cp\u003eEven with incomplete USPS data, addresses with \u003ccode\u003evalidationGranularity\u003c/code\u003e of \u003ccode\u003ePREMISE\u003c/code\u003e can often be accepted, but consider prompting the customer for confirmation.\u003c/p\u003e\n"]]],[],null,["This document describes a number of real-world scenarios where the\nAddress Validation API provides response signals that warrant an *accept* 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 example: accept\n\nThis scenario illustrates an address in which your system would accept an\naddress entered by a customer.\n\n| Address entered | Region |\n|--------------------------------------------|--------|\n| 76 Buckingham Palace Road, London SW1W 9TQ | UK |\n\nVerdict for an acceptable address\n\nThe example below highlights the important signals. \n\n {\n \"inputGranularity\": \"PREMISE\",\n \"validationGranularity\": \"PREMISE\",\n \"geocodeGranularity\": \"PREMISE\",\n \"addressComplete\": true\n }\n\nIn addition to this, the response indicates the following:\n\n- `hasUnconfirmedComponents` remains `false`\n- `hasInferredComponents` remains `false`\n- `hasReplacedComponents` remains `false`\n- `hasSpellCorrectedComponents` remains `false`\n\nWhen combined together, these signals indicate a high-quality address.\n| **Action:** Accept.\n\nEdge case examples: accept\n\nThe following examples cover situations in which the `verdict` indicates address\nquality issues that warrant further investigation. These examples also\nillustrate how your logic can travel from the verdict to the address components\nto obtain a more complete picture in order to enhance your system logic.\n\nNon-US unconfirmed street number\n\nThis example illustrates entry of an Italian address with all address components\npresent, along with no inferred or replaced components. However, the\n`validationGranularity` is `ROUTE`.\n\n| Address entered | Region |\n|-------------------------------------------------------|--------|\n| Via Fonte Grugnale, 14 unit 2, 66054 Vasto CH, Italia | IT |\n\nVerdict for an unconfirmed street number \n\n {\n \"inputGranularity\": \"SUB_PREMISE\",\n \"validationGranularity\": \"ROUTE\",\n \"geocodeGranularity\": \"ROUTE\",\n \"addressComplete\": true,\n \"hasUnconfirmedComponents\": true\n }\n\nFurther investigation of the address components reveals that the street\nnumber is `UNCONFIRMED_BUT_PLAUSIBLE`. \n\n {\n \"text\": \"14\",\n \"componentType\": \"street_number\",\n \"confirmationLevel\": \"UNCONFIRMED_BUT_PLAUSIBLE\"\n }\n\n| **Action:** This address can be accepted without further prompting. However, for a higher confidence level, you can prompt the customer to confirm the address. See [Implementation guidance](/maps/documentation/address-validation/build-validation-logic#implementation_guidance) in **Build your validation logic** for more details.\n\nUS unconfirmed street number\n\nThis example illustrates entry of a US address with all address components\npresent, with no inferred or replaced components. However, the\n`validationGranularity` is `PREMISE_PROXIMITY`.\n\n| Address entered | Region |\n|------------------------------------|--------|\n| 975 Carson Dr, Sunnyvale, CA 94086 | US |\n\nUSPS data for an unconfirmed street number \n\n {\n \"firstAddressLine\": \"975 CARSON DR\",\n \"cityStateZipAddressLine\": \"SUNNYVALE CA 94086\",\n \"city\": \"SUNNYVALE\",\n \"state\": \"CA\",\n \"zipCode\": \"94086\"\n \"dpvConfirmation\": \"N\",\n \"dpvFootnote\": \"AAM3\",\n \"carrierRoute\": \"C031\",\n \"carrierRouteIndicator\": \"D\",\n \"postOfficeCity\": \"SUNNYVALE\",\n \"postOfficeState\": \"CA\",\n \"fipsCountyCode\": \"085\",\n \"county\": \"SANTA CLARA\",\n }\n\n| **Action:** Fix. This example is similar to the previous one, and the address can be accepted as entered. However, the additional `dpvConfirmation` code of `N` provides a strong signal to confirm the address with the customer or prompt them to fix it. The behavior you choose for this case ultimately depends on your required confidence level. See [Implementation guidance](/maps/documentation/address-validation/build-validation-logic#implementation_guidance) in **Build your validation logic** for more details.\n\nIncomplete USPS data for a confirmed address\n\nThis example illustrates entry of a US address with all address components\nconfirmed, with no inferred or replaced components, and a\n`validationGranularity` of `PREMISE`. However, the `uspsData` is not fully\npopulated, and does not contain a `dpvConfirmation` value.\n\n| Address entered | Region |\n|--------------------------------------------------------|--------|\n| 155 Via Condado Way, Palm Beach Gardens, FL 33418-1703 | US |\n\nVerdict for a confirmed address with incomplete USPS data \n\n {\n \"inputGranularity\": \"PREMISE\",\n \"validationGranularity\": \"PREMISE\",\n \"geocodeGranularity\": \"PREMISE\",\n \"addressComplete\": true,\n }\n\nUSPS data for a confirmed address with incomplete USPS data \n\n {\n \"standardizedAddress\": {\n \"firstAddressLine\": \"155 VIA CONDADO WAY\",\n \"cityStateZipAddressLine\": \"PALM BEACH GARDENS\",\n \"city\": \"PALM BEACH GARDENS\",\n \"state\": \"FL\",\n \"zipCode\": \"33418\"\n },\n \"carrierRoute\": \"H018\",\n \"postOfficeCity\": \"PALM BEACH GARDENS\",\n \"postOfficeState\": \"FL\"\n }\n\n| **Action:** Accept. Even though the address is not DPV confirmed by the USPS, the `validationGranularity` of `PREMISE` gives a strong signal that this is a valid address. However, for a higher confidence level, you can prompt the customer to confirm the address. See [Implementation guidance](/maps/documentation/address-validation/build-validation-logic#implementation_guidance) in **Build your validation logic** for more details.\n| **Note:** The service receives updated USPS data periodically, so this example may no longer return incomplete USPS data. This example is meant to be illustrative rather than an accurate portrayal of the API response for this address."]]
