As of January 1, 2020 this library no longer supports Python 2 on the latest released version. Library versions released prior to that date will continue to be available. For more information please visit Python 2 support on Google Cloud.

Types for Google Maps Addressvalidation v1 API

class google.maps.addressvalidation_v1.types.Address(mapping=None, *, ignore_unknown_fields=False, **kwargs)

Bases: proto.message.Message

Details of the post-processed address. Post-processing includes correcting misspelled parts of the address, replacing incorrect parts, and inferring missing parts.

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.

Type

str

postal_address

The post-processed address represented as a postal address.

Type

google.type.postal_address_pb2.PostalAddress

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.

Type

MutableSequence[google.maps.addressvalidation_v1.types.AddressComponent]

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 formatted_address, postal_address, or address_components. An example might be ['street_number', 'route'] for an input like “Boulder, Colorado, 80301, USA”. The list of possible types can be found here.

Type

MutableSequence[str]

unconfirmed_component_types

The types of the components that are present in the address_components but could not be confirmed to be correct. This field is provided for the sake of convenience: its contents are equivalent to iterating through the address_components to find the types of all the components where the [confirmation_level][google.maps.addressvalidation.v1.AddressComponent.confirmation_level] is not [CONFIRMED][google.maps.addressvalidation.v1.AddressComponent.ConfirmationLevel.CONFIRMED] or the [inferred][google.maps.addressvalidation.v1.AddressComponent.inferred] flag is not set to true. The list of possible types can be found here.

Type

MutableSequence[str]

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 ["123235253253"] since that does not look like a valid street number.

Type

MutableSequence[str]

class google.maps.addressvalidation_v1.types.AddressComponent(mapping=None, *, ignore_unknown_fields=False, **kwargs)

Bases: proto.message.Message

Represents an address component, such as a street, city, or state.

component_name

The name for this component.

Type

google.maps.addressvalidation_v1.types.ComponentName

component_type

The type of the address component. See Table 2: Additional types returned by the Places service for a list of possible types.

Type

str

confirmation_level

Indicates the level of certainty that we have that the component is correct.

Type

google.maps.addressvalidation_v1.types.AddressComponent.ConfirmationLevel

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.

Type

bool

spell_corrected

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”.

Type

bool

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.

Type

bool

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.

Type

bool

class ConfirmationLevel(value)

Bases: proto.enums.Enum

The different possible values for confirmation levels.

Values:

CONFIRMATION_LEVEL_UNSPECIFIED (0):

Default value. This value is unused.

CONFIRMED (1):

We were able to verify that this component exists and makes sense in the context of the rest of the address.

UNCONFIRMED_BUT_PLAUSIBLE (2):

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 (3):

This component was not confirmed and is likely to be wrong. For example, a neighborhood that does not fit the rest of the address.

class google.maps.addressvalidation_v1.types.AddressMetadata(mapping=None, *, ignore_unknown_fields=False, **kwargs)

Bases: proto.message.Message

The metadata for the address. metadata is not guaranteed to be fully populated for every address sent to the Address Validation API.

business

Indicates that this is the address of a business. If unset, indicates that the value is unknown.

This field is a member of oneof _business.

Type

bool

po_box

Indicates that the address of a PO box. If unset, indicates that the value is unknown.

This field is a member of oneof _po_box.

Type

bool

residential

Indicates that this is the address of a residence. If unset, indicates that the value is unknown.

This field is a member of oneof _residential.

Type

bool

class google.maps.addressvalidation_v1.types.ComponentName(mapping=None, *, ignore_unknown_fields=False, **kwargs)

Bases: proto.message.Message

A wrapper for the name of the component.

text

The name text. For example, “5th Avenue” for a street name or “1253” for a street number.

Type

str

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.

Type

str

class google.maps.addressvalidation_v1.types.Geocode(mapping=None, *, ignore_unknown_fields=False, **kwargs)

Bases: proto.message.Message

Contains information about the place the input was geocoded to.

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.

Type

google.type.latlng_pb2.LatLng

plus_code

The plus code corresponding to the location.

Type

google.maps.addressvalidation_v1.types.PlusCode

bounds

The bounds of the geocoded place.

Type

google.geo.type.types.Viewport

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.

Type

float

place_id

The PlaceID of the place this input geocodes to.

For more information about Place IDs see here.

Type

str

place_types

The type(s) of place that the input geocoded to. For example, ['locality', 'political']. The full list of types can be found here.

Type

MutableSequence[str]

class google.maps.addressvalidation_v1.types.PlusCode(mapping=None, *, ignore_unknown_fields=False, **kwargs)

Bases: proto.message.Message

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.

global_code

Place’s global (full) code, such as “9FWM33GV+HQ”, representing an 1/8000 by 1/8000 degree area (~14 by 14 meters).

Type

str

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.

Type

str

class google.maps.addressvalidation_v1.types.ProvideValidationFeedbackRequest(mapping=None, *, ignore_unknown_fields=False, **kwargs)

Bases: proto.message.Message

The request for sending validation feedback.

conclusion

Required. The outcome of the sequence of validation attempts.

If this field is set to VALIDATION_CONCLUSION_UNSPECIFIED, an INVALID_ARGUMENT error will be returned.

Type

google.maps.addressvalidation_v1.types.ProvideValidationFeedbackRequest.ValidationConclusion

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.

Type

str

class ValidationConclusion(value)

Bases: proto.enums.Enum

The possible final outcomes of the sequence of address validation requests needed to validate an address.

Values:

VALIDATION_CONCLUSION_UNSPECIFIED (0):

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 (1):

The version of the address returned by the Address Validation API was used for the transaction.

USER_VERSION_USED (2):

The version of the address provided by the user was used for the transaction

UNVALIDATED_VERSION_USED (3):

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 (4):

The transaction was abandoned and the address was not used.

class google.maps.addressvalidation_v1.types.ProvideValidationFeedbackResponse(mapping=None, *, ignore_unknown_fields=False, **kwargs)

Bases: proto.message.Message

The response for validation feedback.

The response is empty if the feedback is sent successfully.

class google.maps.addressvalidation_v1.types.UspsAddress(mapping=None, *, ignore_unknown_fields=False, **kwargs)

Bases: proto.message.Message

USPS representation of a US address.

first_address_line

First address line.

Type

str

firm

Firm name.

Type

str

second_address_line

Second address line.

Type

str

urbanization

Puerto Rican urbanization name.

Type

str

city_state_zip_address_line

City + state + postal code.

Type

str

city

City name.

Type

str

state

2 letter state code.

Type

str

zip_code

Postal code e.g. 10009.

Type

str

zip_code_extension

4-digit postal code extension e.g. 5023.

Type

str

class google.maps.addressvalidation_v1.types.UspsData(mapping=None, *, ignore_unknown_fields=False, **kwargs)

Bases: proto.message.Message

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.

standardized_address

USPS standardized address.

Type

google.maps.addressvalidation_v1.types.UspsAddress

delivery_point_code

2 digit delivery point code

Type

str

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.

Type

str

dpv_confirmation

The possible values for DPV confirmation. Returns a single character or returns no value.

• N: Primary and any secondary number information failed to DPV confirm.

• D: Address was DPV confirmed for the primary number only, and the secondary number information was missing.

• S: Address was DPV confirmed for the primary number only, and the secondary number information was present but not confirmed.

• Y: Address was DPV confirmed for primary and any secondary numbers.

• Empty: If the response does not contain a dpv_confirmation value, the address was not submitted for DPV confirmation.

Type

str

dpv_footnote

The footnotes from delivery point validation. Multiple footnotes may be strung together in the same string.

• AA: Input address matched to the ZIP+4 file

• A1: Input address was not matched to the ZIP+4 file

• BB: Matched to DPV (all components)

• CC: Secondary number not matched and not required

• C1: Secondary number not matched but required

• N1: High-rise address missing secondary number

• M1: Primary number missing

• M3: Primary number invalid

• P1: Input address PO, RR or HC box number missing

• P3: Input address PO, RR, or HC Box number invalid

• F1: Input address matched to a military address

• G1: Input address matched to a general delivery address

• U1: Input address matched to a unique ZIP code

• PB: Input address matched to PBSA record

• RR: DPV confirmed address with PMB information

• R1: DPV confirmed address without PMB information

• R7: Carrier Route R777 or R779 record

• IA: Informed Address identified

• TA: Primary number matched by dropping a trailing alpha

Type

str

dpv_cmra

Indicates if the address is a CMRA (Commercial Mail Receiving Agency)–a private business receiving mail for clients. Returns a single character.

• Y: The address is a CMRA

• N: The address is not a CMRA

Type

str

dpv_vacant

Is this place vacant? Returns a single character.

• Y: The address is vacant

• N: The address is not vacant

Type

str

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.

• Y: The address is not active

• N: The address is active

Type

str

dpv_no_stat_reason_code

Indicates the NoStat type. Returns a reason code as int.

• 1: IDA (Internal Drop Address) – Addresses that do not receive mail directly from the USPS but are delivered to a drop address that services them.

• 2: CDS - Addresses that have not yet become deliverable. For example, a new subdivision where lots and primary numbers have been determined, but no structure exists yet for occupancy.

• 3: Collision - Addresses that do not actually DPV confirm.

• 4: CMZ (College, Military and Other Types) - ZIP + 4 records USPS has incorporated into the data.

• 5: Regular - Indicates addresses not receiving delivery and the addresses are not counted as possible deliveries.

• 6: Secondary Required - The address requires secondary information.

Type

int

dpv_drop

Flag indicates mail is delivered to a single receptable at a site. Returns a single character.

• Y: The mail is delivered to a single receptable at a site.

• N: The mail is not delivered to a single receptable at a site.

Type

str

dpv_throwback

Indicates that mail is not delivered to the street address. Returns a single character.

• Y: The mail is not delivered to the street address.

• N: The mail is delivered to the street address.

Type

str

dpv_non_delivery_days

Flag indicates mail delivery is not performed every day of the week. Returns a single character.

• Y: The mail delivery is not performed every day of the week.

• N: No indication the mail delivery is not performed every day of the week.

Type

str

dpv_non_delivery_days_values

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

Type

int

dpv_no_secure_location

Flag indicates door is accessible, but package will not be left due to security concerns. Returns a single character.

• Y: The package will not be left due to security concerns.

• N: No indication the package will not be left due to security concerns.

Type

str

dpv_pbsa

Indicates the address was matched to PBSA record. Returns a single character.

• Y: The address was matched to PBSA record.

• N: The address was not matched to PBSA record.

Type

str

dpv_door_not_accessible

Flag indicates addresses where USPS cannot knock on a door to deliver mail. Returns a single character.

• Y: The door is not accessible.

• N: No indication the door is not accessible.

Type

str

dpv_enhanced_delivery_code

Indicates that more than one DPV return code is valid for the address. Returns a single character.

• Y: Address was DPV confirmed for primary and any secondary numbers.

• N: Primary and any secondary number information failed to DPV confirm.

• S: Address was DPV confirmed for the primary number only, and the secondary number information was present by not confirmed, or a single trailing alpha on a primary number was dropped to make a DPV match and secondary information required.

• D: Address was DPV confirmed for the primary number only, and the secondary number information was missing.

• R: Address confirmed but assigned to phantom route R777 and R779 and USPS delivery is not provided.

Type

str

carrier_route

The carrier route code. A four character code consisting of a one letter prefix and a three digit route designator.

Prefixes:

• C: Carrier route (or city route)

• R: Rural route

• H: Highway Contract Route

• B: Post Office Box Section

• G: General delivery unit

Type

str

carrier_route_indicator

Carrier route rate sort indicator.

Type

str

ews_no_match

The delivery address is matchable, but the EWS file indicates that an exact match will be available soon.

Type

bool

post_office_city

Main post office city.

Type

str

post_office_state

Main post office state.

Type

str

abbreviated_city

Abbreviated city.

Type

str

fips_county_code

FIPS county code.

Type

str

county

County name.

Type

str

elot_number

Enhanced Line of Travel (eLOT) number.

Type

str

elot_flag

eLOT Ascending/Descending Flag (A/D).

Type

str

lacs_link_return_code

LACSLink return code.

Type

str

lacs_link_indicator

LACSLink indicator.

Type

str

po_box_only_postal_code

PO Box only postal code.

Type

bool

suitelink_footnote

Footnotes from matching a street or highrise record to suite information. If business name match is found, the secondary number is returned.

• A: SuiteLink record match, business address improved.

• 00: No match, business address is not improved.

Type

str

pmb_designator

PMB (Private Mail Box) unit designator.

Type

str

pmb_number

PMB (Private Mail Box) number;

Type

str

address_record_type

Type of the address record that matches the input address.

• F: FIRM. This is a match to a Firm Record, which is the finest level of match available for an address.

• G: GENERAL DELIVERY. This is a match to a General Delivery record.

• H: BUILDING / APARTMENT. This is a match to a Building or Apartment record.

• P: POST OFFICE BOX. This is a match to a Post Office Box.

• R: RURAL ROUTE or HIGHWAY CONTRACT: This is a match to either a Rural Route or a Highway Contract record, both of which may have associated Box Number ranges.

• S: STREET RECORD: This is a match to a Street record containing a valid primary number range.

Type

str

default_address

Indicator that a default address was found, but more specific addresses exists.

Type

bool

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.

Type

str

cass_processed

Indicator that the request has been CASS processed.

Type

bool

class google.maps.addressvalidation_v1.types.ValidateAddressRequest(mapping=None, *, ignore_unknown_fields=False, **kwargs)

Bases: proto.message.Message

The request for validating an address.

address

Required. The address being validated. Unformatted addresses should be submitted via [address_lines][google.type.PostalAddress.address_lines].

The total length of the fields in this input must not exceed 280 characters.

Supported regions can be found here.

The [language_code][google.type.PostalAddress.language_code] value in the input address is reserved for future uses and is ignored today. The validated address result will be populated based on the preferred language for the given address, as identified by the system.

The Address Validation API ignores the values in [recipients][google.type.PostalAddress.recipients] and [organization][google.type.PostalAddress.organization]. Any values in those fields will be discarded and not returned. Please do not set them.

Type

google.type.postal_address_pb2.PostalAddress

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 [response_id][google.maps.addressvalidation.v1.ValidateAddressResponse.response_id] from the very first response in the validation sequence.

Type

str

enable_usps_cass

Enables USPS CASS compatible mode. This affects only the [google.maps.addressvalidation.v1.ValidationResult.usps_data] field of [google.maps.addressvalidation.v1.ValidationResult]. Note: for USPS CASS enabled requests for addresses in Puerto Rico, a [google.type.PostalAddress.region_code] of the address must be provided as “PR”, or an [google.type.PostalAddress.administrative_area] of the address must be provided as “Puerto Rico” (case-insensitive) or “PR”.

It’s recommended to use a componentized address, or alternatively specify at least two [google.type.PostalAddress.address_lines] where the first line contains the street number and name and the second line contains the city, state, and zip code.

Type

bool

session_token

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 starts typing a 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 session_token parameter is omitted, or if you reuse a session token, the session is charged as if no session token was provided (each request is billed separately).

Note: Address Validation can only be used in sessions with the Autocomplete (New) API, not the old Autocomplete API. See https://developers.google.com/maps/documentation/places/web-service/session-pricing for more details.

Type

str

class google.maps.addressvalidation_v1.types.ValidateAddressResponse(mapping=None, *, ignore_unknown_fields=False, **kwargs)

Bases: proto.message.Message

The response to an address validation request.

result

The result of the address validation.

Type

google.maps.addressvalidation_v1.types.ValidationResult

response_id

The UUID that identifies this response. If the address needs to be re-validated, this UUID must accompany the new request.

Type

str

class google.maps.addressvalidation_v1.types.ValidationResult(mapping=None, *, ignore_unknown_fields=False, **kwargs)

Bases: proto.message.Message

The result of validating an address.

verdict

Overall verdict flags

Type

google.maps.addressvalidation_v1.types.Verdict

address

Information about the address itself as opposed to the geocode.

Type

google.maps.addressvalidation_v1.types.Address

geocode

Information about the location and place that the address geocoded to.

Type

google.maps.addressvalidation_v1.types.Geocode

metadata

Other information relevant to deliverability. metadata is not guaranteed to be fully populated for every address sent to the Address Validation API.

Type

google.maps.addressvalidation_v1.types.AddressMetadata

usps_data

Extra deliverability flags provided by USPS. Only provided in region US and PR.

Type

google.maps.addressvalidation_v1.types.UspsData

class google.maps.addressvalidation_v1.types.Verdict(mapping=None, *, ignore_unknown_fields=False, **kwargs)

Bases: proto.message.Message

High level overview of the address validation result and geocode.

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 validation_granularity below.

For example, if the input address includes a specific apartment number, then the input_granularity here will be SUB_PREMISE. If we cannot match the apartment number in the databases or the apartment number is invalid, the validation_granularity will likely be PREMISE or below.

Type

google.maps.addressvalidation_v1.types.Verdict.Granularity

validation_granularity

The granularity level that the API can fully validate the address to. For example, an validation_granularity of PREMISE indicates all address components at the level of PREMISE or more coarse can be validated.

Per address component validation result can be found in [google.maps.addressvalidation.v1.Address.address_components].

Type

google.maps.addressvalidation_v1.types.Verdict.Granularity

geocode_granularity

Information about the granularity of the [geocode][google.maps.addressvalidation.v1.ValidationResult.geocode]. This can be understood as the semantic meaning of how coarse or fine the geocoded location is.

This can differ from the validation_granularity above occasionally. For example, our database might record the existence of an apartment number but do not have a precise location for the apartment within a big apartment complex. In that case, the validation_granularity will be SUB_PREMISE but the geocode_granularity will be PREMISE.

Type

google.maps.addressvalidation_v1.types.Verdict.Granularity

address_complete

The address is considered complete if there are no unresolved tokens, no unexpected or missing address components. See [missing_component_types][google.maps.addressvalidation.v1.Address.missing_component_types], [unresolved_tokens][google.maps.addressvalidation.v1.Address.unresolved_tokens] or [unexpected][google.maps.addressvalidation.v1.AddressComponent.unexpected] fields for more details.

Type

bool

has_unconfirmed_components

At least one address component cannot be categorized or validated, see [google.maps.addressvalidation.v1.Address.address_components] for details.

Type

bool

has_inferred_components

At least one address component was inferred (added) that wasn’t in the input, see [google.maps.addressvalidation.v1.Address.address_components] for details.

Type

bool

has_replaced_components

At least one address component was replaced, see [google.maps.addressvalidation.v1.Address.address_components] for details.

Type

bool

class Granularity(value)

Bases: proto.enums.Enum

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.

Values:

GRANULARITY_UNSPECIFIED (0):

Default value. This value is unused.

SUB_PREMISE (1):

Below-building level result, such as an apartment.

PREMISE (2):

Building-level result.

PREMISE_PROXIMITY (3):

A geocode that approximates the building-level location of the address.

BLOCK (4):

The address or geocode indicates a block. Only used in regions which have block-level addressing, such as Japan.

ROUTE (5):

The geocode or address is granular to route, such as a street, road, or highway.

OTHER (6):

All other granularities, which are bucketed together since they are not deliverable.