Understand a basic address validation response

The Address Validation API provides a response body as a JSON object that contains two top-level properties:

• result, an object of type ValidationResult
• responseID

{
  "result": {
    // Validation verdict.
    "verdict": {},
    // Address details determined by the API.
    "address": {},
    // The geocode generated for the input address.
    "geocode": {},
    // Information indicating if the address is a business, residence, etc.
    "metadata": {},
    // Information about the address from the US Postal Service
    // ("US" and "PR" addresses only).
    "uspsData": {},
  },
  // A unique identifier generated for every request to the API.
  "responseId": "ID"
}

This document focuses on the result object. For information on the responseID, see Handle updated addresses.

The verdict property

The verdict property summarizes the results of the address validation and should be the first property to evaluate when building address checking logic. The property can return a variety of fields, depending on the quality of the output address. For example, the following shows the verdict property of an address of good quality, which returns 4 fields for this particular request:

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

The following sections summarize all fields in the verdict property.

Granularity of the address

Address granularity refers to the level of detail used in determining the specificity of an address or geocode. Address specificity in the validationGranularity response is a key signal for whether or not an address is deliverable.

The verdict property returns these granularity signals:

• inputGranularity — Describes the level of detail captured from the address sent to the Address Validation API. The level of address detail in the request influences the level of address detail in the validation response. For example, an address with an inputGranularity below PREMISE below level does not typically result in a validationGranularity to a PREMISE level.
• validationGranularity — The granularity level that the Address Validation API can fully validate the address to. In most cases, a granularity level of PREMISE or SUB_PREMISE indicates a quality address that is likely deliverable.
• geocodeGranularity — Describes the level of detail of the geocode associated with the address. For example, Google records might indicate the existence of an apartment number, but not a precise location for that particular apartment within a large apartment complex. In that case, the validationGranularity is SUB_PREMISE but the geocodeGranularityisPREMISE`.

Completeness of the address

The verdict returns the addressComplete property as a signal for a high-quality address, which means specifically that it has no missing, unresolved, or unexpected components:

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

When the address has missing, unresolved, or unexpected components, the field is set to false.

Address quality

A number of possible fields indicate either problems with address components, or adjustments to them, such as inferred or missing address components. For example, the following verdict property indicates an address with unconfirmed components and a missing addressComplete field:

"verdict": {
    "inputGranularity": "PREMISE",
    "validationGranularity": "OTHER",
    "geocodeGranularity": "OTHER",
    "hasUnconfirmedComponents": true,
    "hasInferredComponents": true
}

The address and addressComponent properties

The address property provides formatting for the processed address provided in the request, along with component-level summaries of the address, including misspelled parts of the address, replaced incorrect parts, and inferred missing parts.

The addressComponent property is a subcomponent of address which provides a detailed listing of the elements—or components—of the address that the Address Validation API has processed. The API identifies each component field provides by its name, type, and confirmation level.

The geocode property

The geocode property indicates the geocoded location associated with the input address. This property provides details about the location itself, such as its place ID.

The metadata property

This property might not be populated for every address processed by the Address Validation API, but indicates if the address is of type residential, business, or a PO Box.

The uspsData property

This property provides useful information for United States postal addresses. However, it's not guaranteed to be fully populated for every address validated by the service. For that reason, you shouldn't rely on this property as the sole means to validate addresses, but instead check the verdict and address as well.