Add subpremises to address - examples (US only)

This document describes a number of real-world scenarios where the Address Validation API provides response signals that warrant an add subpremises behavior from your system. These signals are only available for US addresses. See Workflow overview in Build your validation logic for context.

Common example: add subpremises

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

Address entered	Region
1450 Brickell Avenue, Miami, FL 33131-4065	US

Verdict for an address missing a subpremises

The example below highlights the important signal.

{
  "inputGranularity": "PREMISE",
  "validationGranularity": "PREMISE",
  "geocodeGranularity": "PREMISE",
  "possibleNextAction": "CONFIRM_ADD_SUBPREMISES"
}

Edge case example: add subpremises

The following example covers a situation in which the verdict indicates address quality issues that warrant further investigation. This examples also illustrates how your logic can travel from the verdict to the address components to 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 an incorrect postal code.

Address entered	Region
1450 Brickell Avenue, FL 33132-4065	US

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 has been 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
}