Add subpremises to address - examples (US only)

This document describes a number of real-world scenarios where theAddress Validation API provides response signals that warrant anadd subpremisesbehavior from your system. These signals are only available for US addresses.SeeExample workflows inBuild your validation logic for context.

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

Common example: add subpremises

This scenario illustrates an address in which your system might prompt acustomer to add a unit number to the address.

Address enteredRegion
1450 Brickell Avenue, Miami, FL 33131-4065US

Verdict for an address missing a subpremises

The example below highlights the important signal.

{  "inputGranularity": "PREMISE",  "validationGranularity": "PREMISE",  "geocodeGranularity": "PREMISE","possibleNextAction": "CONFIRM_ADD_SUBPREMISES"}
Action: For this address, you might prompt your user to add a unit number.

Edge case example: add subpremises

The following example covers a situation in which theverdict indicatesaddress quality issues that warrant further investigation. This examples alsoillustrates how your logic can travel from the verdict to the address componentsto obtain a more complete picture in order to enhance your system logic.

Missing subpremises and inferred and replaced components

This example illustrates entry of a US address with a missing locality and anincorrect postal code.

Address enteredRegion
1450 Brickell Avenue, FL 33132-4065US

Verdict for a missing subpremises and inferred and replaced components

{  "inputGranularity": "PREMISE",  "validationGranularity": "PREMISE",  "geocodeGranularity": "PREMISE","hasInferredComponents": true,"hasReplacedComponents": true,"possibleNextAction": "CONFIRM_ADD_SUBPREMISES"}

Further investigation of the address components reveals that the locality hasbeen inferred, and the postal code has been replaced.

{   "componentName": {     "text": "33131",   }   "componentType": "postal_code",   "confirmationLevel": "CONFIRMED","replaced": true},{   "componentName": {     "text": "Miami",     "languageCode": "en"   }   "componentType": "locality",   "confirmationLevel": "CONFIRMED","inferred": true}
Action: For this address, you might prompt your user to add a unit number, or prompt them to review the entire 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.