미국에서 주소를 확인할 때 Address Validation API 서비스는 반환의 uspsData 부분도 채울 수 있습니다.
이 객체는 항상 채워지는 것이 아니므로 이 속성을 주소를 검증하는 유일한 수단으로 사용해서는 안 되며, 대신 평결과 주소 구성요소를 시스템에 통합해야 합니다.
USPS 배송 지점 확인 (DPV)
uspsData 응답의 일부로 dpvConfirmation 필드는 USPS가 제공된 주소로 배송할 수 있는지 여부를 알리기 위해 단일 문자를 반환합니다.
이 필드를 사용하여 다음을 확인할 수 있습니다.
주소 유효성 검사
주소에 하위 건물 번호가 누락된 경우
하위 건물 번호가 USPS 데이터 시스템에 없는 경우
서비스는 4개의 dpvConfirmation 값 중 하나를 반환하거나 dpvConfirmation 값을 전혀 반환하지 않습니다. 아래 표에는 가능한 5가지 결과 각각에 대해 논리에서 사용할 수 있는 동작이 나와 있습니다. 이 로직에 관한 자세한 내용은 유효성 검사 로직 빌드의 워크플로 예시를 참고하세요.
값
동작
설명
N 또는 비어 있음
주소 수정
주소가 DPV 확인되지 않았습니다.
즉, USPS에서 입력한 번지가 입력한 도로 (경로)에 있는 것으로 인식하지 못하며 배송이 불가능할 수 있습니다.
D
하위 건물 추가
주 번호에 대해서만 DPV가 확인되었고 보조 번호 정보가 누락되었습니다.
즉, 입력한 번지가 입력한 도로에 있지만 완전히 인증되고 배송 가능한 주소에 도달하려면 유효한 하위 번호도 제공해야 합니다. 즉, 입력에 하위 전제가 누락되었습니다.
S
주소 확인
주 번호에 대해서만 주소의 DPV가 확인되었으며 보조 번호 정보는 있지만 확인되지 않았습니다.
이는 입력한 경로에 입력한 건물 번호가 있지만 USPS에 따르면 제공된 하위 건물 번호가 해당 건물 내에 없음을 의미합니다.
Y
주소 수락
기본 번호와 보조 번호의 주소가 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 (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에서 완전히 배송 가능합니다. 이렇게 하면 API가 양질의 주소를 반환했다는 확신을 가질 수 있으며 제공된 대로 사용할 수 있습니다. 언제나처럼 고객에게 확인을 요청할지 여부를 결정할 때는 위험 수준을 고려하세요.
참고: DPV는 Address Validation API가 맞춤법 수정과 같은 입력을 변경했는지 여부를 나타내지 않습니다.
미국 주소의 보안 메시지
이 섹션에서는 인위적으로 생성된 주소에 대해 USPS 데이터에 제공된 보안 플래그를 다룹니다. 이 보안 조치는 제출된 주소가 합법적으로 획득되지 않고 인위적으로 구성된 것으로 보이는 경우를 감지하여 주소 목록이 인위적으로 생성되는 것을 방지하도록 설계되었습니다.
이러한 상황은 매우 드물게 발생합니다.
USPS에서 인위적으로 생성된 주소를 식별하면 응답의 uspsData 속성의 errorMessage 필드에 문제를 설명하는 오류 메시지가 포함됩니다. 예를 들면 다음과 같습니다.
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.
[[["이해하기 쉬움","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(UTC)"],[[["\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."]]
