- HTTP request
- Request body
- Response body
- PostalAddress
- LanguageOptions
- ValidationResult
- Verdict
- Granularity
- Address
- AddressComponent
- ComponentName
- ConfirmationLevel
- Geocode
- LatLng
- PlusCode
- Viewport
- AddressMetadata
- UspsData
- UspsAddress
Validates an address.
HTTP request
POST https://addressvalidation.googleapis.com/v1:validateAddress
The URL uses gRPC Transcoding syntax.
Request body
The request body contains data with the following structure:
JSON representation |
---|
{ "address": { object ( |
Fields | |
---|---|
address |
Required. The address being validated. Unformatted addresses should be submitted via The total length of the fields in this input must not exceed 280 characters. Supported regions can be found here. The The Address Validation API ignores the values in |
previous |
This field must be empty for the first address validation request. If more requests are necessary to fully validate a single address (for example if the changes the user makes after the initial validation need to be re-validated), then each followup request must populate this field with the |
enable |
Enables USPS CASS compatible mode. This affects only the It's recommended to use a componentized |
language |
Optional. Preview: This 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 the Google Maps Platform Service Specific Terms. For more information, see the launch stage descriptions. Enables the Address Validation API to include additional information in the response. |
session |
Optional. A string which identifies an Autocomplete session for billing purposes. Must be a URL and filename safe base64 string with at most 36 ASCII characters in length. Otherwise an INVALID_ARGUMENT error is returned. The session begins when the user makes an Autocomplete query, and concludes when they select a place and a call to Place Details or Address Validation is made. Each session can have multiple Autocomplete queries, followed by one Place Details or Address Validation request. The credentials used for each request within a session must belong to the same Google Cloud Console project. Once a session has concluded, the token is no longer valid; your app must generate a fresh token for each session. If the Note: Address Validation can only be used in sessions with the Autocomplete (New) API, not the Autocomplete API. See https://developers.google.com/maps/documentation/places/web-service/session-pricing for more details. |
Response body
The response to an address validation request.
If successful, the response body contains data with the following structure:
JSON representation |
---|
{
"result": {
object ( |
Fields | |
---|---|
result |
The result of the address validation. |
response |
The UUID that identifies this response. If the address needs to be re-validated, this UUID must accompany the new request. |
PostalAddress
Represents a postal address, e.g. for postal delivery or payments addresses. Given a postal address, a postal service can deliver items to a premise, P.O. Box or similar. It is not intended to model geographical locations (roads, towns, mountains).
In typical usage an address would be created via user input or from importing existing data, depending on the type of process.
Advice on address input / editing: - Use an internationalization-ready address widget such as https://github.com/google/libaddressinput) - Users should not be presented with UI elements for input or editing of fields outside countries where that field is used.
For more guidance on how to use this schema, please see: https://support.google.com/business/answer/6397478
JSON representation |
---|
{ "revision": integer, "regionCode": string, "languageCode": string, "postalCode": string, "sortingCode": string, "administrativeArea": string, "locality": string, "sublocality": string, "addressLines": [ string ], "recipients": [ string ], "organization": string } |
Fields | |
---|---|
revision |
The schema revision of the |
region |
Optional. CLDR region code of the country/region of the address. See https://cldr.unicode.org/ and https://www.unicode.org/cldr/charts/30/supplemental/territory_information.html for details. Example: "CH" for Switzerland. If the region code is not provided, it will be inferred from the address. For best performance, it is recommended to include the region code if you know it. Having inconsistent or repeated regions can lead to poor performance, for example, if the |
language |
The language code in the input address is reserved for future uses and is ignored today. The API returns the address in the appropriate language for where the address is located. |
postal |
Optional. Postal code of the address. Not all countries use or require postal codes to be present, but where they are used, they may trigger additional validation with other parts of the address (e.g. state/zip validation in the U.S.A.). |
sorting |
Optional. Additional, country-specific, sorting code. This is not used in most regions. Where it is used, the value is either a string like "CEDEX", optionally followed by a number (e.g. "CEDEX 7"), or just a number alone, representing the "sector code" (Jamaica), "delivery area indicator" (Malawi) or "post office indicator" (e.g. Côte d'Ivoire). |
administrative |
Optional. Highest administrative subdivision which is used for postal addresses of a country or region. For example, this can be a state, a province, an oblast, or a prefecture. Specifically, for Spain this is the province and not the autonomous community (e.g. "Barcelona" and not "Catalonia"). Many countries don't use an administrative area in postal addresses. E.g. in Switzerland this should be left unpopulated. |
locality |
Optional. Generally refers to the city/town portion of the address. Examples: US city, IT comune, UK post town. In regions of the world where localities are not well defined or do not fit into this structure well, leave locality empty and use addressLines. |
sublocality |
Optional. Sublocality of the address. For example, this can be neighborhoods, boroughs, districts. |
address |
Required. Unstructured address lines describing the lower levels of an address. |
recipients[] |
Please avoid setting this field. The Address Validation API does not currently use it. Although at this time the API will not reject requests with this field set, the information will be discarded and will not be returned in the response. |
organization |
Please avoid setting this field. The Address Validation API does not currently use it. Although at this time the API will not reject requests with this field set, the information will be discarded and will not be returned in the response. |
LanguageOptions
Preview: This 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 the Google Maps Platform Service Specific Terms. For more information, see the launch stage descriptions.
Enables the Address Validation API to include additional information in the response.
JSON representation |
---|
{ "returnEnglishLatinAddress": boolean } |
Fields | |
---|---|
return |
Preview: Return a |
ValidationResult
The result of validating an address.
JSON representation |
---|
{ "verdict": { object ( |
Fields | |
---|---|
verdict |
Overall verdict flags |
address |
Information about the address itself as opposed to the geocode. |
geocode |
Information about the location and place that the address geocoded to. |
metadata |
Other information relevant to deliverability. |
usps |
Extra deliverability flags provided by USPS. Only provided in region |
english |
Preview: This 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 the Google Maps Platform Service Specific Terms. For more information, see the launch stage descriptions. The address translated to English. Translated addresses are not reusable as API input. The service provides them so that the user can use their native language to confirm or deny the validation of the originally-provided address. If part of the address doesn't have an English translation, the service returns that part in an alternate language that uses a Latin script. See here for an explanation of how the alternate language is selected. If part of the address doesn't have any translations or transliterations in a language that uses a Latin script, the service returns that part in the local language associated with the address. Enable this output by using the Note: the |
Verdict
High level overview of the address validation result and geocode.
JSON representation |
---|
{ "inputGranularity": enum ( |
Fields | |
---|---|
input |
The granularity of the input address. This is the result of parsing the input address and does not give any validation signals. For validation signals, refer to For example, if the input address includes a specific apartment number, then the |
validation |
The granularity level that the API can fully validate the address to. For example, an Per address component validation result can be found in |
geocode |
Information about the granularity of the This can differ from the |
address |
The address is considered complete if there are no unresolved tokens, no unexpected or missing address components. If unset, indicates that the value is |
has |
At least one address component cannot be categorized or validated, see |
has |
At least one address component was inferred (added) that wasn't in the input, see |
has |
At least one address component was replaced, see |
Granularity
The various granularities that an address or a geocode can have. When used to indicate granularity for an address, these values indicate with how fine a granularity the address identifies a mailing destination. For example, an address such as "123 Main Street, Redwood City, CA, 94061" identifies a PREMISE
while something like "Redwood City, CA, 94061" identifies a LOCALITY
. However, if we are unable to find a geocode for "123 Main Street" in Redwood City, the geocode returned might be of LOCALITY
granularity even though the address is more granular.
Enums | |
---|---|
GRANULARITY_UNSPECIFIED |
Default value. This value is unused. |
SUB_PREMISE |
Below-building level result, such as an apartment. |
PREMISE |
Building-level result. |
PREMISE_PROXIMITY |
A geocode that approximates the building-level location of the address. |
BLOCK |
The address or geocode indicates a block. Only used in regions which have block-level addressing, such as Japan. |
ROUTE |
The geocode or address is granular to route, such as a street, road, or highway. |
OTHER |
All other granularities, which are bucketed together since they are not deliverable. |
Address
Details of the post-processed address. Post-processing includes correcting misspelled parts of the address, replacing incorrect parts, and inferring missing parts.
JSON representation |
---|
{ "formattedAddress": string, "postalAddress": { object ( |
Fields | |
---|---|
formatted |
The post-processed address, formatted as a single-line address following the address formatting rules of the region where the address is located. Note: the format of this address may not match the format of the address in the |
postal |
The post-processed address represented as a postal address. |
address |
Unordered list. The individual address components of the formatted and corrected address, along with validation information. This provides information on the validation status of the individual components. Address components are not ordered in a particular way. Do not make any assumptions on the ordering of the address components in the list. |
missing |
The types of components that were expected to be present in a correctly formatted mailing address but were not found in the input AND could not be inferred. Components of this type are not present in |
unconfirmed |
The types of the components that are present in the |
unresolved |
Any tokens in the input that could not be resolved. This might be an input that was not recognized as a valid part of an address. For example, for an input such as "Parcel 0000123123 & 0000456456 Str # Guthrie Center IA 50115 US", the unresolved tokens might look like |
AddressComponent
Represents an address component, such as a street, city, or state.
JSON representation |
---|
{ "componentName": { object ( |
Fields | |
---|---|
component |
The name for this component. |
component |
The type of the address component. See Table 2: Additional types returned by the Places service for a list of possible types. |
confirmation |
Indicates the level of certainty that we have that the component is correct. |
inferred |
Indicates that the component was not part of the input, but we inferred it for the address location and believe it should be provided for a complete address. |
spell |
Indicates a correction to a misspelling in the component name. The API does not always flag changes from one spelling variant to another, such as when changing "centre" to "center". It also does not always flag common misspellings, such as when changing "Amphitheater Pkwy" to "Amphitheatre Pkwy". |
replaced |
Indicates the name of the component was replaced with a completely different one, for example a wrong postal code being replaced with one that is correct for the address. This is not a cosmetic change, the input component has been changed to a different one. |
unexpected |
Indicates an address component that is not expected to be present in a postal address for the given region. We have retained it only because it was part of the input. |
ComponentName
A wrapper for the name of the component.
JSON representation |
---|
{ "text": string, "languageCode": string } |
Fields | |
---|---|
text |
The name text. For example, "5th Avenue" for a street name or "1253" for a street number. |
language |
The BCP-47 language code. This will not be present if the component name is not associated with a language, such as a street number. |
ConfirmationLevel
The different possible values for confirmation levels.
Enums | |
---|---|
CONFIRMATION_LEVEL_UNSPECIFIED |
Default value. This value is unused. |
CONFIRMED |
We were able to verify that this component exists and makes sense in the context of the rest of the address. |
UNCONFIRMED_BUT_PLAUSIBLE |
This component could not be confirmed, but it is plausible that it exists. For example, a street number within a known valid range of numbers on a street where specific house numbers are not known. |
UNCONFIRMED_AND_SUSPICIOUS |
This component was not confirmed and is likely to be wrong. For example, a neighborhood that does not fit the rest of the address. |
Geocode
Contains information about the place the input was geocoded to.
JSON representation |
---|
{ "location": { object ( |
Fields | |
---|---|
location |
The geocoded location of the input. Using place IDs is preferred over using addresses, latitude/longitude coordinates, or plus codes. Using coordinates when routing or calculating driving directions will always result in the point being snapped to the road nearest to those coordinates. This may not be a road that will quickly or safely lead to the destination and may not be near an access point to the property. Additionally, when a location is reverse geocoded, there is no guarantee that the returned address will match the original. |
plus |
The plus code corresponding to the |
bounds |
The bounds of the geocoded place. |
feature |
The size of the geocoded place, in meters. This is another measure of the coarseness of the geocoded location, but in physical size rather than in semantic meaning. |
place |
The PlaceID of the place this input geocodes to. For more information about Place IDs see here. |
place |
The type(s) of place that the input geocoded to. For example, |
LatLng
An object that represents a latitude/longitude pair. This is expressed as a pair of doubles to represent degrees latitude and degrees longitude. Unless specified otherwise, this object must conform to the WGS84 standard. Values must be within normalized ranges.
JSON representation |
---|
{ "latitude": number, "longitude": number } |
Fields | |
---|---|
latitude |
The latitude in degrees. It must be in the range [-90.0, +90.0]. |
longitude |
The longitude in degrees. It must be in the range [-180.0, +180.0]. |
PlusCode
Plus code (http://plus.codes) is a location reference with two formats: global code defining a 14mx14m (1/8000th of a degree) or smaller rectangle, and compound code, replacing the prefix with a reference location.
JSON representation |
---|
{ "globalCode": string, "compoundCode": string } |
Fields | |
---|---|
global |
Place's global (full) code, such as "9FWM33GV+HQ", representing an 1/8000 by 1/8000 degree area (~14 by 14 meters). |
compound |
Place's compound code, such as "33GV+HQ, Ramberg, Norway", containing the suffix of the global code and replacing the prefix with a formatted name of a reference entity. |
Viewport
A latitude-longitude viewport, represented as two diagonally opposite low
and high
points. A viewport is considered a closed region, i.e. it includes its boundary. The latitude bounds must range between -90 to 90 degrees inclusive, and the longitude bounds must range between -180 to 180 degrees inclusive. Various cases include:
If
low
=high
, the viewport consists of that single point.If
low.longitude
>high.longitude
, the longitude range is inverted (the viewport crosses the 180 degree longitude line).If
low.longitude
= -180 degrees andhigh.longitude
= 180 degrees, the viewport includes all longitudes.If
low.longitude
= 180 degrees andhigh.longitude
= -180 degrees, the longitude range is empty.If
low.latitude
>high.latitude
, the latitude range is empty.
Both low
and high
must be populated, and the represented box cannot be empty (as specified by the definitions above). An empty viewport will result in an error.
For example, this viewport fully encloses New York City:
{ "low": { "latitude": 40.477398, "longitude": -74.259087 }, "high": { "latitude": 40.91618, "longitude": -73.70018 } }
JSON representation |
---|
{ "low": { object ( |
Fields | |
---|---|
low |
Required. The low point of the viewport. |
high |
Required. The high point of the viewport. |
AddressMetadata
The metadata for the address. metadata
is not guaranteed to be fully populated for every address sent to the Address Validation API.
JSON representation |
---|
{ "business": boolean, "poBox": boolean, "residential": boolean } |
Fields | |
---|---|
business |
Indicates that this is the address of a business. If unset, indicates that the value is unknown. |
po |
Indicates that the address of a PO box. If unset, indicates that the value is unknown. |
residential |
Indicates that this is the address of a residence. If unset, indicates that the value is unknown. |
UspsData
The USPS data for the address. uspsData
is not guaranteed to be fully populated for every US or PR address sent to the Address Validation API. It's recommended to integrate the backup address fields in the response if you utilize uspsData as the primary part of the response.
JSON representation |
---|
{
"standardizedAddress": {
object ( |
Fields | |
---|---|
standardized |
USPS standardized address. |
delivery |
2 digit delivery point code |
delivery |
The delivery point check digit. This number is added to the end of the delivery_point_barcode for mechanically scanned mail. Adding all the digits of the delivery_point_barcode, deliveryPointCheckDigit, postal code, and ZIP+4 together should yield a number divisible by 10. |
dpv |
The possible values for DPV confirmation. Returns a single character or returns no value.
|
dpv |
The footnotes from delivery point validation. Multiple footnotes may be strung together in the same string.
|
dpv |
Indicates if the address is a CMRA (Commercial Mail Receiving Agency)--a private business receiving mail for clients. Returns a single character.
|
dpv |
Is this place vacant? Returns a single character.
|
dpv |
Is this a no stat address or an active address? No stat addresses are ones which are not continuously occupied or addresses that the USPS does not service. Returns a single character.
|
dpv |
Indicates the NoStat type. Returns a reason code as int.
|
dpv |
Flag indicates mail is delivered to a single receptable at a site. Returns a single character.
|
dpv |
Indicates that mail is not delivered to the street address. Returns a single character.
|
dpv |
Flag indicates mail delivery is not performed every day of the week. Returns a single character.
|
dpv |
Integer identifying non-delivery days. It can be interrogated using bit flags: 0x40 – Sunday is a non-delivery day 0x20 – Monday is a non-delivery day 0x10 – Tuesday is a non-delivery day 0x08 – Wednesday is a non-delivery day 0x04 – Thursday is a non-delivery day 0x02 – Friday is a non-delivery day 0x01 – Saturday is a non-delivery day |
dpv |
Flag indicates door is accessible, but package will not be left due to security concerns. Returns a single character.
|
dpv |
Indicates the address was matched to PBSA record. Returns a single character.
|
dpv |
Flag indicates addresses where USPS cannot knock on a door to deliver mail. Returns a single character.
|
dpv |
Indicates that more than one DPV return code is valid for the address. Returns a single character.
|
carrier |
The carrier route code. A four character code consisting of a one letter prefix and a three digit route designator. Prefixes:
|
carrier |
Carrier route rate sort indicator. |
ews |
The delivery address is matchable, but the EWS file indicates that an exact match will be available soon. |
post |
Main post office city. |
post |
Main post office state. |
abbreviated |
Abbreviated city. |
fips |
FIPS county code. |
county |
County name. |
elot |
Enhanced Line of Travel (eLOT) number. |
elot |
eLOT Ascending/Descending Flag (A/D). |
lacs |
LACSLink return code. |
lacs |
LACSLink indicator. |
po |
PO Box only postal code. |
suitelink |
Footnotes from matching a street or highrise record to suite information. If business name match is found, the secondary number is returned.
|
pmb |
PMB (Private Mail Box) unit designator. |
pmb |
PMB (Private Mail Box) number; |
address |
Type of the address record that matches the input address.
|
default |
Indicator that a default address was found, but more specific addresses exists. |
error |
Error message for USPS data retrieval. This is populated when USPS processing is suspended because of the detection of artificially created addresses. The USPS data fields might not be populated when this error is present. |
cass |
Indicator that the request has been CASS processed. |
UspsAddress
USPS representation of a US address.
JSON representation |
---|
{ "firstAddressLine": string, "firm": string, "secondAddressLine": string, "urbanization": string, "cityStateZipAddressLine": string, "city": string, "state": string, "zipCode": string, "zipCodeExtension": string } |
Fields | |
---|---|
first |
First address line. |
firm |
Firm name. |
second |
Second address line. |
urbanization |
Puerto Rican urbanization name. |
city |
City + state + postal code. |
city |
City name. |
state |
2 letter state code. |
zip |
Postal code e.g. 10009. |
zip |
4-digit postal code extension e.g. 5023. |