Places UI Kit: A ready-to-use library that provides room for customization and low-code development. Try it out, and share yourinput on your UI Kit experience.

Understand a basic address validation response

Note: This document describes the basic elements of an address validationresponse for an address of high quality. For guidance on working withreal-world address scenarios and building logic around more complex responses,see SeeBuild your validation logic.

The Address Validation API response contains these top-level properties:

{// Address details determined by the API."address":{},// Validation verdict."verdict":{},// 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"}

Theverdict property

Key Point: Use theverdictproperty to get a baseline summary of the quality of the address.

Theverdict property summarizes the results of the address validation andshould be the first property to evaluate when building address checking logic.The property can return a variety of fields, depending on the quality of theoutput address. For example, the following shows theverdict property of anaddress of good quality, which returns the following fields for this particularrequest:

"verdict":{"inputGranularity":"PREMISE","validationGranularity":"PREMISE","geocodeGranularity":"PREMISE","possibleNextAction":"ACCEPT","addressComplete":true,"hasUnconfirmedComponents":false,"hasInferredComponents":true,"hasReplacedComponents":false}

The following sections summarize all fields in theverdict property.

SeeVerdict in the reference guide.

Granularity of the address

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

Theverdict property returns these granularity signals:

  • inputGranularity — Describes the level of detail captured from theaddress sent to the Address Validation in Maps JavaScript API. The level of address detail in therequest influences the level of address detail in the validation response.For example, an address with aninputGranularity belowPREMISE belowlevel does not typically result in avalidationGranularity to aPREMISElevel.
  • validationGranularity — The granularity level that theAddress Validation in Maps JavaScript API can fully validate the address to. In most cases, agranularity level ofPREMISE orSUB_PREMISE indicates a quality addressthat is likely deliverable.
  • geocodeGranularity — Describes the level of detail of the geocodeassociated with the address. For example, Google records might indicate theexistence of an apartment number, but not a precise location for thatparticular apartment within a large apartment complex. In that case, thevalidationGranularity isSUB_PREMISE but thegeocodeGranularity isPREMISE.
SeeGranularity in the reference guide.

Completeness of the address

The verdict returns theaddressComplete property as a signal for ahigh-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 fieldis set tofalse.

Note: When theaddressComplete property does not appear in the verdictupon manual inspection, its value is false. In this case you should either querythe verdict for the presence of theaddressComplete property or query theproperty directly. SeeAddress quality below for an example.
SeeaddressComplete underVerdict andAddress in the reference guide.

Address quality

A number of possible fields indicate either problems with address components, oradjustments to them, such as inferred or missing address components. Forexample, the followingverdict property indicates an address with unconfirmedcomponents and a missingaddressComplete field:

"verdict":{"inputGranularity":"PREMISE","validationGranularity":"OTHER","geocodeGranularity":"OTHER","hasUnconfirmedComponents":true,"hasInferredComponents":true}
SeeVerdictin the reference guide.

Possible next action

This product or feature is in Preview (pre-GA). Pre-GA products and features might have limited support, and changes to pre-GA products and features might not be compatible with other pre-GA versions. Pre-GA Offerings are covered by theGoogle Maps Platform Service Specific Terms. For more information, see thelaunch stage descriptions.

ThepossibleNextActionverdict field offers an interpretive summary of the API response, intended toassist in determining a potential subsequent action to take. This field isderived from other fields in the API response and should not be considered as aguarantee of address accuracy or deliverability.

Theaddress andaddressComponent properties

Key Point: Use theaddress property to obtain address formatting. Use itssubcomponentaddressComponent for investigating errors and providinginformation about those errors to your customers. However, don't build yourintegration to rely on the specific confirmation level for address components.SeeBuild your validation logic for integration guidance.

Theaddress property provides formatting for the processed address provided inthe request, along with component-level summaries of the address, includingmisspelled parts of the address, replaced incorrect parts, and inferred missingparts.

SeeAddress in the reference guide.

TheaddressComponent property is a subcomponent ofaddress which providesa detailed listing of the elements—or components—of the address that theAddress Validation in Maps JavaScript API has processed. The API identifies each componentfield provides by its name, type, and confirmation level.

SeeaddressComponent in the reference guide.

Thegeocode property

Key Point: Use thegeocode property as a convenience to obtain the geocode orplace ID when your logic previously called the Geocoding API.

Thegeocode property indicates the geocoded location associated with the inputaddress. This property provides details about the location itself, such asits place ID.

SeeGeocode in the reference guide.

Themetadata property

Key Point: Use themetadata property to determine the type of propertyassociated with the address: residential, PO Box, or business.

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

SeeAddress Validation API coverage and the reference forAddress metadata.

TheuspsData property

Key Point: Use theuspsData property to obtain delivery confidence levels andother USPS details about US addresses.

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

SeeHandle United States addresses and the reference forUSPSData.

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-12-18 UTC.