Accept address - examples

  • The Address Validation API provides signals to determine if an address should be accepted by your system, even with minor uncertainties.

  • Addresses withvalidationGranularity ofPREMISE and no unconfirmed/inferred/replaced components are generally safe to accept.

  • Addresses withUNCONFIRMED_BUT_PLAUSIBLE street numbers can be accepted, but consider prompting the customer for confirmation for higher confidence.

  • US addresses withdpvConfirmation of 'N' might require customer confirmation or correction, depending on your system's confidence requirements.

  • Even with incomplete USPS data, addresses withvalidationGranularity ofPREMISE can often be accepted, but consider prompting the customer for confirmation.

This document describes a number of real-world scenarios where theAddress Validation API provides response signals that warrant anaccept behaviorfrom your system. SeeExample workflows inBuild your validation logic for context.

Note: The examples here are illustrative, but don't cover all scenarios.

Common example: accept

This scenario illustrates an address in which your system would accept anaddress entered by a customer.

Address enteredRegion
76 Buckingham Palace Road, London SW1W 9TQUK

Verdict for an acceptable address

The example below highlights the important signals.

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

In addition to this, the response indicates the following:

  • hasUnconfirmedComponents remainsfalse
  • hasInferredComponents remainsfalse
  • hasReplacedComponents remainsfalse
  • hasSpellCorrectedComponents remainsfalse

When combined together, these signals indicate a high-quality address.

Action: Accept.

Edge case examples: accept

The following examples cover situations in which theverdict indicates addressquality issues that warrant further investigation. These examples alsoillustrate how your logic can travel from the verdict to the address componentsto obtain a more complete picture in order to enhance your system logic.

Non-US unconfirmed street number

This example illustrates entry of an Italian address with all address componentspresent, along with no inferred or replaced components. However, thevalidationGranularity isROUTE.

Address enteredRegion
Via Fonte Grugnale, 14 unit 2, 66054 Vasto CH, ItaliaIT

Verdict for an unconfirmed street number

{  "inputGranularity": "SUB_PREMISE","validationGranularity": "ROUTE",  "geocodeGranularity": "ROUTE","addressComplete": true,  "hasUnconfirmedComponents": true}

Further investigation of the address components reveals that the streetnumber isUNCONFIRMED_BUT_PLAUSIBLE.

{   "text": "14",   "componentType": "street_number","confirmationLevel": "UNCONFIRMED_BUT_PLAUSIBLE"}
Action: This address can be accepted without further prompting. However, for a higher confidence level, you can prompt the customer to confirm the address. SeeImplementation guidance inBuild your validation logic for more details.

US unconfirmed street number

This example illustrates entry of a US address with all address componentspresent, with no inferred or replaced components. However, thevalidationGranularity isPREMISE_PROXIMITY.

Address enteredRegion
975 Carson Dr, Sunnyvale, CA 94086US

USPS data for an unconfirmed street number

{   "firstAddressLine": "975 CARSON DR",   "cityStateZipAddressLine": "SUNNYVALE CA 94086",   "city": "SUNNYVALE",   "state": "CA",   "zipCode": "94086""dpvConfirmation": "N",   "dpvFootnote": "AAM3",   "carrierRoute": "C031",   "carrierRouteIndicator": "D",   "postOfficeCity": "SUNNYVALE",   "postOfficeState": "CA",   "fipsCountyCode": "085",   "county": "SANTA CLARA",}
Action: Fix. This example is similar to the previous one, and the address can be accepted as entered. However, the additionaldpvConfirmation code ofN 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. SeeImplementation guidance inBuild your validation logic for more details.

Incomplete USPS data for a confirmed address

This example illustrates entry of a US address with all address componentsconfirmed, with no inferred or replaced components, and avalidationGranularity ofPREMISE. However, theuspsData is not fullypopulated, and does not contain adpvConfirmation value.

Address enteredRegion
155 Via Condado Way, Palm Beach Gardens, FL 33418-1703US

Verdict for a confirmed address with incomplete USPS data

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

USPS data for a confirmed address with incomplete USPS data

{  "standardizedAddress": {    "firstAddressLine": "155 VIA CONDADO WAY",    "cityStateZipAddressLine": "PALM BEACH GARDENS",    "city": "PALM BEACH GARDENS",    "state": "FL",    "zipCode": "33418"  },  "carrierRoute": "H018",  "postOfficeCity": "PALM BEACH GARDENS",  "postOfficeState": "FL"}
Action: Accept. Even though the address is not DPV confirmed by the USPS, thevalidationGranularity ofPREMISE 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. SeeImplementation guidance inBuild your validation logic for more details.Note: The service receives updated USPS data periodically, so this example mayno longer return incomplete USPS data. This example is meant to be illustrativerather than an accurate portrayal of the API response for this address.

Except as otherwise noted, the content of this page is licensed under theCreative Commons Attribution 4.0 License, and code samples are licensed under theApache 2.0 License. For details, see theGoogle Developers Site Policies. Java is a registered trademark of Oracle and/or its affiliates.

Last updated 2025-11-21 UTC.