Understand a basic address validation response

  • The Address Validation API response contains a result object with properties like verdict, address, geocode, metadata, and uspsData to provide detailed information about the validated address.

  • The verdict property offers a summary of the address quality, including granularity and completeness indicators, which are crucial for determining deliverability.

  • The address and addressComponent properties provide formatted address details and insights into potential errors or adjustments made during validation.

  • The geocode property offers the geocoded location and place ID, while the metadata property might indicate if the address is residential, business, or a PO Box.

  • The uspsData property provides additional details for US addresses, such as delivery confidence levels, but should be used in conjunction with other properties for comprehensive validation.

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

{
  "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,
  "possibleNextAction": "ACCEPT"
}

The following sections summarize all fields in the verdict property.

See Verdict in the reference guide.

Possible next action

The possibleNextAction property offers an interpretive summary of the rest of the API response, with the goal of helping you determine whether or not you should prompt your customer to review or make edits to their address. See Build your validation logic for more details.

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`.
See Granularity in the reference guide.

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,
    "possibleNextAction": "ACCEPT"
}

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

See addressComplete under Verdict and Address in the reference guide.

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
}
See Verdict in the reference guide.

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.

See Address in the reference guide.

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.

See addressComponent in the reference guide.

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.

See Geocode in the reference guide.

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.

See Address Validation API coverage and the reference for Address metadata.

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.

See Handle United States addresses and the reference for UspsData.