feat: [google-maps-addressvalidation] add session token support for Autocomplete (New) sessions that end with a call to Address Validation (#12331)

BEGIN_COMMIT_OVERRIDE

feat: add session token support for Autocomplete (New) sessions that end
with a call to Address Validation

feat: add new fields to USPS data

docs: update proto field descriptions

END_COMMIT_OVERRIDE

- [ ] Regenerate this pull request now.

feat: add new fields to USPS data
docs: update proto field descriptions

PiperOrigin-RevId: 608369029

Source-Link:
googleapis/googleapis@5ff3e52

Source-Link:
googleapis/googleapis-gen@c182835
Copy-Tag:
eyJwIjoicGFja2FnZXMvZ29vZ2xlLW1hcHMtYWRkcmVzc3ZhbGlkYXRpb24vLk93bEJvdC55YW1sIiwiaCI6ImMxODI4MzU4YmU0MTJiYTAyZTQ1YmZiYWUzYWZjMmIzZGFkZDVkMzIifQ==

---------

Co-authored-by: Owl Bot <gcf-owl-bot[bot]@users.noreply.github.com>
Co-authored-by: ohmayr <[email protected]>

Author: gcf-owl-bot[bot]

packages/google-maps-addressvalidation/google/maps/addressvalidation_v1/types/address.py

@@ -138,10 +138,13 @@ class AddressComponent(proto.Message):
             location and believe it should be provided for a
             complete address.
         spell_corrected (bool):
-            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.
+            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 (bool):
             Indicates the name of the component was
             replaced with a completely different one, for

packages/google-maps-addressvalidation/google/maps/addressvalidation_v1/types/address_validation_service.py

@@ -50,8 +50,8 @@ class ValidateAddressRequest(proto.Message):
             The total length of the fields in this input must not exceed
             280 characters.
 
-            Supported regions can be found in the
-            `FAQ <https://developers.google.com/maps/documentation/address-validation/faq#which_regions_are_currently_supported>`__.
+            Supported regions can be found
+            `here <https://developers.google.com/maps/documentation/address-validation/coverage>`__.
 
             The [language_code][google.type.PostalAddress.language_code]
             value in the input address is reserved for future uses and
@@ -89,6 +89,30 @@ class ValidateAddressRequest(proto.Message):
             [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.
+        session_token (str):
+            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.
     """
 
     address: postal_address_pb2.PostalAddress = proto.Field(
@@ -104,6 +128,10 @@ class ValidateAddressRequest(proto.Message):
         proto.BOOL,
         number=3,
     )
+    session_token: str = proto.Field(
+        proto.STRING,
+        number=5,
+    )
 
 
 class ValidateAddressResponse(proto.Message):
@@ -329,7 +357,7 @@ class Granularity(proto.Enum):
             PREMISE (2):
                 Building-level result.
             PREMISE_PROXIMITY (3):
-                A geocode that should be very close to the
+                A geocode that approximates the
                 building-level location of the address.
             BLOCK (4):
                 The address or geocode indicates a block.

packages/google-maps-addressvalidation/google/maps/addressvalidation_v1/types/usps_data.py

@@ -110,30 +110,33 @@ class UspsData(proto.Message):
             should yield a number divisible by 10.
         dpv_confirmation (str):
             The possible values for DPV confirmation. Returns a single
-            character.
+            character or returns no value.
 
-            -  ``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.
             -  ``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.
         dpv_footnote (str):
             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 (present but
-               invalid)
+            -  ``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 RR or HC box number missing
+            -  ``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
@@ -143,6 +146,9 @@ class UspsData(proto.Message):
             -  ``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
         dpv_cmra (str):
             Indicates if the address is a CMRA (Commercial Mail
             Receiving Agency)--a private business receiving mail for
@@ -163,6 +169,95 @@ class UspsData(proto.Message):
 
             -  ``Y``: The address is not active
             -  ``N``: The address is active
+        dpv_no_stat_reason_code (int):
+            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.
+        dpv_drop (str):
+            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.
+        dpv_throwback (str):
+            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.
+        dpv_non_delivery_days (str):
+            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.
+        dpv_non_delivery_days_values (int):
+            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_no_secure_location (str):
+            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.
+        dpv_pbsa (str):
+            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.
+        dpv_door_not_accessible (str):
+            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.
+        dpv_enhanced_delivery_code (str):
+            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.
         carrier_route (str):
             The carrier route code. A four character code consisting of
             a one letter prefix and a three digit route designator.
@@ -276,6 +371,42 @@ class UspsData(proto.Message):
         proto.STRING,
         number=8,
     )
+    dpv_no_stat_reason_code: int = proto.Field(
+        proto.INT32,
+        number=29,
+    )
+    dpv_drop: str = proto.Field(
+        proto.STRING,
+        number=30,
+    )
+    dpv_throwback: str = proto.Field(
+        proto.STRING,
+        number=31,
+    )
+    dpv_non_delivery_days: str = proto.Field(
+        proto.STRING,
+        number=32,
+    )
+    dpv_non_delivery_days_values: int = proto.Field(
+        proto.INT32,
+        number=33,
+    )
+    dpv_no_secure_location: str = proto.Field(
+        proto.STRING,
+        number=34,
+    )
+    dpv_pbsa: str = proto.Field(
+        proto.STRING,
+        number=35,
+    )
+    dpv_door_not_accessible: str = proto.Field(
+        proto.STRING,
+        number=36,
+    )
+    dpv_enhanced_delivery_code: str = proto.Field(
+        proto.STRING,
+        number=37,
+    )
     carrier_route: str = proto.Field(
         proto.STRING,
         number=9,

packages/google-maps-addressvalidation/scripts/fixup_addressvalidation_v1_keywords.py

@@ -40,7 +40,7 @@ class addressvalidationCallTransformer(cst.CSTTransformer):
     CTRL_PARAMS: Tuple[str] = ('retry', 'timeout', 'metadata')
     METHOD_TO_PARAMS: Dict[str, Tuple[str]] = {
         'provide_validation_feedback': ('conclusion', 'response_id', ),
-        'validate_address': ('address', 'previous_response_id', 'enable_usps_cass', ),
+        'validate_address': ('address', 'previous_response_id', 'enable_usps_cass', 'session_token', ),
     }
 
     def leave_Call(self, original: cst.Call, updated: cst.Call) -> cst.CSTNode: