عند التحقّق من صحة العناوين في الولايات المتحدة، يمكن لخدمة Address Validation API أيضًا ملء جزء uspsData من الردّ.
بما أنّ هذا العنصر لا تتم تعبئته دائمًا، لا يجب الاعتماد على هذه السمة كوسيلة وحيدة للتحقّق من صحة العناوين، بل يجب أيضًا دمج الحكم ومكوّنات العنوان في نظامك.
التحقّق من نقطة التسليم في USPS (DPV)
كجزء من استجابة uspsData، يعرض الحقل dpvConfirmation حرفًا واحدًا لإعلامك بما إذا كان بإمكان خدمة البريد الأمريكية (USPS) إرسال الطرود إلى العنوان المقدَّم.
يمكنك استخدام هذا الحقل لتحديد ما يلي:
صلاحية العنوان
إذا كان رقم المبنى الفرعي غير متوفّر في العنوان
إذا لم يكن رقم المكان الفرعي متوفّرًا في نظام بيانات USPS
تعرض الخدمة إحدى قيم dpvConfirmation الأربع أو لا تعرض أي قيمة dpvConfirmation على الإطلاق. يعرض الجدول أدناه السلوك المحتمل الذي يمكن أن تستخدمه منطقك لكل نتيجة من النتائج الخمس المحتملة. لمزيد من التفاصيل حول هذه المنطق، راجِع أمثلة على سير العمل في إنشاء منطق التحقّق من الصحة.
القيمة
السلوك
الوصف
N أو فارغ
تصحيح العنوان
لم يتم تأكيد العنوان باستخدام نظام DPV.
وهذا يعني أنّ هيئة البريد الأمريكية لا تتعرّف على رقم المبنى الذي تم إدخاله والموجود في الشارع (الطريق) الذي تم إدخاله، ومن المحتمل ألا تتمكّن من إرسال الطرود إلى هذا العنوان.
D
إضافة مكان فرعي
تم تأكيد العنوان من خلال DPV لرقم الهاتف الأساسي فقط، ولم تتوفّر معلومات رقم الهاتف الثانوي.
هذا يعني أنّ رقم المكان الذي تم إدخاله متوفّر في الشارع الذي تم إدخاله، ولكن للوصول إلى عنوان تم التحقّق من صحته بالكامل/يمكن تسليمه، يجب أيضًا تقديم رقم مكان فرعي صالح. بعبارة أخرى، لم تكن الفرضية الفرعية متوفرة في الإدخال.
S
تأكيد العنوان
تم تأكيد العنوان من خلال DPV للرقم الأساسي فقط، وكانت معلومات الرقم الثانوي متوفّرة ولكن لم يتم تأكيدها.
هذا يعني أنّ رقم المكان الذي تم إدخاله متوفّر في المسار الذي تم إدخاله، ولكن المكان الفرعي الذي تم تقديمه غير متوفّر في هذا المبنى، وفقًا لخدمة البريد الأمريكية.
نعم
قبول العنوان
تم تأكيد العنوان من خلال DPV للأرقام الأساسية والثانوية.
وهذا يعني أنّ خدمة USPS يمكنها إيصال الرسائل إلى هذا العنوان بالكامل، بما في ذلك رقم المبنى الفرعي، إن وُجد.
تتناول بقية هذا القسم سيناريوهات واقعية تستخدم رموز DPV.
مثال على DPV N - تصحيح العنوان
يستخدم هذا المثال رقم شارع غير موجود في عنوان صالح.
العنوان الذي تم إدخاله: 12 Amphitheatre Parkway, Mountain View, CA, 94043
المنطقة: الولايات المتحدة
يعرض الحقل dpvConfirmation ما يلي: N
هذه إشارة قوية للغاية إلى أنّ رقم المكان غير متوفّر على هذا المسار. وكما هو الحال مع العناوين الأخرى التي تتضمّن مشاكل، يجب أن يطلب نظامك من المستخدم إجراء تصحيحات.
مثال على DPV D - إضافة موقع فرعي
يستخدم هذا المثال مكتب Google في نيويورك، ولكنّه لا يتضمّن
موقعًا فرعيًا وهو جزء مطلوب من العنوان. يمكنك الاطّلاع على ذلك باستخدام العنوان في العرض التوضيحي بدون معلومات عن العنوان الفرعي.
العنوان الذي تم إدخاله: 111 8th Avenue, New York, NY, 10011
المنطقة: الولايات المتحدة
يعرض الحقل dpvConfirmation ما يلي: D
يؤكّد ذلك أنّ العنوان الفرعي كان غير متوفّر في الإدخال. للحصول على قيمة DPV
تساوي Y، يجب تضمين فرضية فرعية صالحة كجزء من الإدخال. على سبيل المثال، يمكنك تضمين قيمة فرعية صالحة للمكان FL 4 (الطابق الرابع) للحصول على قيمة dpvConfirmation تساوي Y.
مثال على DPV S - تأكيد العنوان
يستخدم هذا المثال رقمًا فرعيًا غير متوفّر في المبنى:
العنوان الذي تم إدخاله: 1600 Amphitheatre Parkway, Suite 101, Mountain View, CA,
94043
المنطقة: الولايات المتحدة
يعرض الحقل dpvConfirmation ما يلي: S
يشير ذلك إلى أنّه على الرغم من أنّ 1600 Amphitheatre Parkway هو عنوان صالح، إلا أنّ
المكان الفرعي Suite 101 ليس جزءًا صالحًا من العنوان. ننصحك بالتأكّد من هذه المعلومات مع المستخدم ومنحه فرصة لتصحيحها.
مثال على DPV Y - قبول العنوان
يستخدم هذا المثال عنوان Googleplex في ماونتن فيو، كاليفورنيا كعنوان صالح معروف.
العنوان الذي تم إدخاله: 1600 Amphitheatre Parkway, Mountain View, CA, 94043
المنطقة: الولايات المتحدة
يعرض الحقل dpvConfirmation ما يلي: Y
يجب أن يكون العنوان قابلاً للتسليم بالكامل من خلال خدمة USPS. يمنحك ذلك درجة عالية جدًا من الثقة في أنّ واجهة برمجة التطبيقات عرضت عنوانًا بجودة جيدة، ويمكنك على الأرجح استخدامه كما هو. كما هو الحال دائمًا، يجب مراعاة
مستوى المخاطرة عند تحديد ما إذا كان يجب أن تطلب من
عميلك تأكيد عملية الشراء أم لا.
ملاحظة: لا يشير DPV إلى ما إذا كانت واجهة برمجة التطبيقات Address Validation API قد أجرت أي تغييرات على الإدخال، مثل تصحيح الأخطاء الإملائية.
رسائل الأمان للعناوين في الولايات المتحدة
يتناول هذا القسم علامات الأمان المتوفّرة في بيانات USPS للعناوين التي تم إنشاؤها بشكل مصطنع. تم تصميم إجراء الأمان هذا لمنع إنشاء قائمة عناوين بشكل مصطنع من خلال رصد الحالات التي يبدو فيها أنّ العنوان المُرسَل تم إنشاؤه بشكل مصطنع ولم يتم الحصول عليه بشكل مشروع.
ومن المفترض أن تكون هذه الحالات نادرة جدًا.
عندما تحدّد USPS عنوانًا تم إنشاؤه بشكل مصطنع، يحتوي الحقل errorMessage في السمة uspsData الخاصة بالرد على رسالة خطأ تصف المشكلة. على سبيل المثال:
AMS API processing was terminated due to the detection of what is determined to
be an artificially created address. No address beyond this point has been
validated and/or processed. If you believe this address was identified in error,
please contact your Vendor.
تاريخ التعديل الأخير: 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\u003eThis document outlines address validation techniques specific to the United States, focusing on leveraging USPS data for enhanced accuracy.\u003c/p\u003e\n"],["\u003cp\u003eThe USPS Delivery Point Verification (DPV) codes (N, D, S, Y) provide insights into address deliverability, allowing systems to identify potential issues and prompt users for corrections.\u003c/p\u003e\n"],["\u003cp\u003eWhile the \u003ccode\u003euspsData\u003c/code\u003e object offers valuable information for US addresses, it's crucial to incorporate other validation response elements for comprehensive verification due to its potential for incomplete population.\u003c/p\u003e\n"],["\u003cp\u003eSecurity measures are in place to detect artificially created addresses, triggering an error message within the \u003ccode\u003euspsData\u003c/code\u003e if such an address is identified, while other response properties remain unaffected.\u003c/p\u003e\n"]]],["The document details how to use USPS data for US address validation via an API. The `uspsData` object, specifically the `dpvConfirmation` field, indicates address deliverability. `Y` means the address is fully deliverable; `S` means the sub-premise is unconfirmed; `D` indicates a missing sub-premise; `N` or empty implies the primary address is invalid. Artificially created addresses trigger an error message in `uspsData`, and their detection does not affect other response properties. The provided examples can be used as a reference for what kind of values and scenarios could be encountered when using this API.\n"],null,["\u003cbr /\u003e\n\nThis document covers address validation specific to the United States:\n\n- [Using USPS data in your workflow](#using-usps-data)\n- [USPS Delivery Point Verification](#usps-delivery) fields (dpv)\n- [Security messages](#security-messages)\n\nUSPS data in your workflow\n\nWhen validating addresses in the United States, the Address Validation API service\ncan also populate the [uspsData](https://developers.google.com/maps/documentation/address-validation/reference/rest/v1/TopLevel/validateAddress#uspsdata) portion of the return.\n| **Key Point:** If your system primarily or exclusively handles US addresses, you may elect to use this response object as a first point of reference in your checking logic. However, it's important to know that the `uspsData` object is not guaranteed to be fully populated for every address validated by the service.\n\nBecause this object is not always populated, you shouldn't rely on this\nproperty as the sole means to validate addresses, but instead incorporate the\nverdict and address components into your system as well.\n\nUSPS Delivery Point Verification (DPV)\n\nAs part of the `uspsData` response, the `dpvConfirmation` field returns a single\ncharacter to let you know if the USPS can deliver to the provided address.\n\nYou can use this field to determine the following:\n\n- address validity.\n- if a sub-premise number is missing from the address.\n- if the sub-premise number does not exist in the USPS data system.\n\nThe service either returns one of four `dpvConfirmation` values or it does not\nreturn a `dpvConfirmation` value at all. The table below shows the possible\nbehavior your logic could use for each of the 5 possible outcomes. For more\ndetails on this logic, see\n[Example workflows](/maps/documentation/address-validation/build-validation-logic#example-workflows) in\n**Build your validation logic.**\n\n| **Value** | **Behavior** | **Description** |\n|------------|---------------------|-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|\n| N or empty | Fix the address | The address was not DPV confirmed. This means the USPS does not recognize the entered premise number existing on the entered street (route), and likely cannot deliver there. |\n| D | Add a subpremises | The address was DPV confirmed for the primary number only, and the secondary number information was missing. \u003cbr /\u003e This means that the premise number entered exists on the entered street, but to reach a fully verified/deliverable address, a valid sub-premise number also needs to be provided. In other words, the sub-premise was missing from the input. |\n| S | Confirm the address | The address was DPV confirmed for the primary number only, and the secondary number information was present but not confirmed. This means that the premise number entered exists on the entered route, but the sub-premise provided does not exist within that building, according to USPS. |\n| Y | Accept the address | The address was DPV confirmed for primary and any secondary numbers. This means the address is fully deliverable by USPS, including the sub-premise number, if applicable. |\n\nThe rest of this section discusses real world scenarios that use the DPV codes.\n\nDPV N example - fix the address\n\nThis example uses a non-existent street number on an otherwise valid address.\n\n- **Address entered**: 12 Amphitheatre Parkway, Mountain View, CA, 94043\n- **Region**: USA\n- The `dpvConfirmation` field returns: `N`\n\nThis is an **extremely strong signal** that this premise number does not exist\non this route. As with other problematic addresses, your system should prompt\nthe user for corrections.\n\nDPV D example - add a subpremises\n\nThis example uses the Google office in New York, but does not contain a\nsub-premise which is a required part of the address. You can see this by using\nthe address in the [demo](https://developers.google.com/maps/documentation/address-validation/demo) without sub-premise information.\n\n- **Address entered**: 111 8th Avenue, New York, NY, 10011\n- **Region**: USA\n- The `dpvConfirmation` field returns: `D`\n\nThis confirms that the sub-premise was missing from the input. To get to a DPV\nof Y, a valid sub-premise must be included as part of the input. For example,\nyou could include a valid sub-premise of *FL 4* (4th Floor) to obtain a\n`dpvConfirmation` value of Y.\n\nDPV S example - confirm the address\n\nThis example uses a sub-premise number that does not exist within the building:\n\n- **Address entered**: 1600 Amphitheatre Parkway, Suite 101, Mountain View, CA, 94043\n- **Region**: USA\n- The `dpvConfirmation` field returns: `S`\n\nThis indicates that, while 1600 Amphitheatre Parkway is a valid address, the\nsub-premise *Suite 101* is not a valid part of the address. You might consider\nconfirming this information with the user and provide an opportunity for a\ncorrection.\n\nDPV Y example - accept the address\n\nThis example uses the Googleplex address in Mountain View, CA as a\nknown valid address.\n\n- **Address entered**: 1600 Amphitheatre Parkway, Mountain View, CA, 94043\n- **Region**: USA\n- The `dpvConfirmation` field returns: `Y`\n\nThe address is fully deliverable by USPS. This gives you a very high degree of\nconfidence that the API returned an address of good quality, and you can likely\nuse it as provided. As always, consider your\n[risk level](https://developers.google.com/maps/documentation/address-validation/build-validation-logic#implementation_guidance) when deciding whether or not to prompt\nyour customer for confirmation.\n\n**Note**: The DPV does not indicate if the Address Validation API has made any\nchanges to the input, such as a spell correction.\n\nSecurity messages for US addresses\n\nThis section covers the security flags provided in the USPS data for\nartificially created addresses. This security measure is designed to prevent the\nartificial creation of an address list by detecting when a submitted address\nappears to have been constructed artificially and not obtained legitimately.\nThis should be a very rare occurrence.\n\nWhen the USPS identifies an artificially created address, the `errorMessage`\nfield of the [uspsData](https://developers.google.com/maps/documentation/address-validation/reference/rest/v1/TopLevel/validateAddress#uspsdata) property of the response contains an\nerror message describing the issue. For example: \n\n AMS API processing was terminated due to the detection of what is determined to\n be an artificially created address. No address beyond this point has been\n validated and/or processed. If you believe this address was identified in error,\n please contact your Vendor.\n\n| **Note:** When the `uspsData` indicates an artificial address, the response for other properties in the Address Validation API response remain unaffected."]]
