Index
AddressValidation
(interface)Address
(message)AddressComponent
(message)AddressComponent.ConfirmationLevel
(enum)AddressMetadata
(message)ComponentName
(message)Geocode
(message)PlusCode
(message)ProvideValidationFeedbackRequest
(message)ProvideValidationFeedbackRequest.ValidationConclusion
(enum)ProvideValidationFeedbackResponse
(message)UspsAddress
(message)UspsData
(message)ValidateAddressRequest
(message)ValidateAddressResponse
(message)ValidationResult
(message)Verdict
(message)Verdict.Granularity
(enum)
AddressValidation
The service for validating addresses.
ProvideValidationFeedback |
---|
Feedback about the outcome of the sequence of validation attempts. This should be the last call made after a sequence of validation calls for the same address, and should be called once the transaction is concluded. This should only be sent once for the sequence of |
ValidateAddress |
---|
Validates an address. |
Address
Details of the post-processed address. Post-processing includes correcting misspelled parts of the address, replacing incorrect parts, and inferring missing parts.
Fields | |
---|---|
formatted_address |
The post-processed address, formatted as a single-line address following the address formatting rules of the region where the address is located. |
postal_address |
The post-processed address represented as a postal address. |
address_components[] |
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_component_types[] |
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_component_types[] |
The types of the components that are present in the |
unresolved_tokens[] |
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 in an input like "123235253253 Main St, San Francisco, CA, 94105", the unresolved tokens may look like |
AddressComponent
Represents an address component, such as a street, city, or state.
Fields | |
---|---|
component_name |
The name for this component. |
component_type |
The type of the address component. See Table 2: Additional types returned by the Places service for a list of possible types. |
confirmation_level |
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_corrected |
Indicates the spelling of the component name was corrected in a minor way, for example by switching two characters that appeared in the wrong order. This indicates a cosmetic change. |
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. |
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. |
AddressMetadata
The metadata for the address. metadata
is not guaranteed to be fully populated for every address sent to the Address Validation API.
Fields | |
---|---|
business |
Indicates that this is the address of a business. If unset, indicates that the value is unknown. |
po_box |
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. |
ComponentName
A wrapper for the name of the component.
Fields | |
---|---|
text |
The name text. For example, "5th Avenue" for a street name or "1253" for a street number. |
language_code |
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. |
Geocode
Contains information about the place the input was geocoded to.
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_code |
The plus code corresponding to the |
bounds |
The bounds of the geocoded place. |
feature_size_meters |
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_id |
The PlaceID of the place this input geocodes to. For more information about Place IDs see here. |
place_types[] |
The type(s) of place that the input geocoded to. For example, |
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.
Fields | |
---|---|
global_code |
Place's global (full) code, such as "9FWM33GV+HQ", representing an 1/8000 by 1/8000 degree area (~14 by 14 meters). |
compound_code |
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. |
ProvideValidationFeedbackRequest
The request for sending validation feedback.
Fields | |
---|---|
conclusion |
Required. The outcome of the sequence of validation attempts. If this field is set to |
response_id |
Required. The ID of the response that this feedback is for. This should be the [response_id][google.maps.addressvalidation.v1.ValidateAddressRequest.response_id] from the first response in a series of address validation attempts. |
ValidationConclusion
The possible final outcomes of the sequence of address validation requests needed to validate an address.
Enums | |
---|---|
VALIDATION_CONCLUSION_UNSPECIFIED |
This value is unused. If the ProvideValidationFeedbackRequest.conclusion field is set to VALIDATION_CONCLUSION_UNSPECIFIED , an INVALID_ARGUMENT error will be returned. |
VALIDATED_VERSION_USED |
The version of the address returned by the Address Validation API was used for the transaction. |
USER_VERSION_USED |
The version of the address provided by the user was used for the transaction |
UNVALIDATED_VERSION_USED |
A version of the address that was entered after the last validation attempt but that was not re-validated was used for the transaction. |
UNUSED |
The transaction was abandoned and the address was not used. |
ProvideValidationFeedbackResponse
The response for validation feedback.
The response is empty if the feedback is sent successfully.
UspsAddress
USPS representation of a US address.
Fields | |
---|---|
first_address_line |
First address line. |
firm |
Firm name. |
second_address_line |
Second address line. |
urbanization |
Puerto Rican urbanization name. |
city_state_zip_address_line |
City + state + postal code. |
city |
City name. |
state |
2 letter state code. |
zip_code |
Postal code e.g. 10009. |
zip_code_extension |
4-digit postal code extension e.g. 5023. |
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.
Fields | |
---|---|
standardized_address |
USPS standardized address. |
delivery_point_code |
2 digit delivery point code |
delivery_point_check_digit |
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, delivery_point_check_digit, postal code, and ZIP+4 together should yield a number divisible by 10. |
dpv_confirmation |
The possible values for DPV confirmation. Returns a single character.
|
dpv_footnote |
The footnotes from delivery point validation. Multiple footnotes may be strung together in the same string.
|
dpv_cmra |
Indicates if the address is a CMRA (Commercial Mail Receiving Agency)--a private business receiving mail for clients. Returns a single character.
|
dpv_vacant |
Is this place vacant? Returns a single character.
|
dpv_no_stat |
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.
|
carrier_route |
The carrier route code. A four character code consisting of a one letter prefix and a three digit route designator. Prefixes:
|
carrier_route_indicator |
Carrier route rate sort indicator. |
ews_no_match |
The delivery address is matchable, but the EWS file indicates that an exact match will be available soon. |
post_office_city |
Main post office city. |
post_office_state |
Main post office state. |
abbreviated_city |
Abbreviated city. |
fips_county_code |
FIPS county code. |
county |
County name. |
elot_number |
Enhanced Line of Travel (eLOT) number. |
elot_flag |
eLOT Ascending/Descending Flag (A/D). |
lacs_link_return_code |
LACSLink return code. |
lacs_link_indicator |
LACSLink indicator. |
po_box_only_postal_code |
PO Box only postal code. |
suitelink_footnote |
Footnotes from matching a street or highrise record to suite information. If business name match is found, the secondary number is returned.
|
pmb_designator |
PMB (Private Mail Box) unit designator. |
pmb_number |
PMB (Private Mail Box) number; |
address_record_type |
Type of the address record that matches the input address.
|
default_address |
Indicator that a default address was found, but more specific addresses exists. |
error_message |
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_processed |
Indicator that the request has been CASS processed. |
ValidateAddressRequest
The request for validating an address.
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_response_id |
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_usps_cass |
Enables USPS CASS compatible mode. This affects only the It's recommended to use a componentized |
ValidateAddressResponse
The response to an address validation request.
Fields | |
---|---|
result |
The result of the address validation. |
response_id |
The UUID that identifies this response. If the address needs to be re-validated, this UUID must accompany the new request. |
ValidationResult
The result of validating an address.
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_data |
Extra deliverability flags provided by USPS. Only provided in region |
Verdict
High level overview of the address validation result and geocode.
Fields | |
---|---|
input_granularity |
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_granularity |
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_granularity |
Information about the granularity of the This can differ from the |
address_complete |
The address is considered complete if there are no unresolved tokens, no unexpected or missing address components. See |
has_unconfirmed_components |
At least one address component cannot be categorized or validated, see |
has_inferred_components |
At least one address component was inferred (added) that wasn't in the input, see |
has_replaced_components |
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. |