The Address Validation API provides a response body as a JSON object that contains two top-level properties:
result
, an object of typeValidationResult
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.
See Verdict in the reference guide. |
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 aninputGranularity
belowPREMISE
below level does not typically result in avalidationGranularity
to aPREMISE
level.validationGranularity
— The granularity level that the Address Validation API can fully validate the address to. In most cases, a granularity level ofPREMISE
orSUB_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, thevalidationGranularity
isSUB_PREMISE
but thegeocodeGranularity
is
PREMISE`.
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
}
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 .
|