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

PiperOrigin-RevId: 608369029

google/maps/addressvalidation/v1/address.proto

@@ -118,9 +118,11 @@ message AddressComponent {
   // for a complete address.
   bool inferred = 4;
 
-  // 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".
   bool spell_corrected = 5;
 
   // Indicates the name of the component was replaced with a completely

google/maps/addressvalidation/v1/address_validation_service.proto

@@ -70,8 +70,8 @@ message ValidateAddressRequest {
   // 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 is ignored today. The
@@ -107,6 +107,28 @@ message ValidateAddressRequest {
   // contains the street number and name and the second line contains the city,
   // state, and zip code.
   bool enable_usps_cass = 3;
+
+  // 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.
+  string session_token = 5 [(google.api.field_behavior) = OPTIONAL];
 }
 
 // The response to an address validation request.
@@ -204,8 +226,7 @@ message Verdict {
     // Building-level result.
     PREMISE = 2;
 
-    // A geocode that should be very close to the building-level location of
-    // the address.
+    // A geocode that approximates the building-level location of the address.
     PREMISE_PROXIMITY = 3;
 
     // The address or geocode indicates a block. Only used in regions which

google/maps/addressvalidation/v1/addressvalidation_v1.yaml

@@ -12,7 +12,4 @@ documentation:
     addresses. Given an address, it returns information about the correctness
     of the components of the parsed address, a geocode, and a verdict on the
     deliverability of the parsed address.
-  overview: |-
-    The Address Validation API allows developers to validate an address and
-    its components, standardize the address for mailing, and determine the
-    best known geocode for it.
+  overview: '<!--#include file="/geo/platform/address_validation/g3doc/overview.md"-->'

google/maps/addressvalidation/v1/usps_data.proto

@@ -73,15 +73,18 @@ message UspsData {
   // code, and ZIP+4 together should yield a number divisible by 10.
   string delivery_point_check_digit = 3;
 
-  // The possible values for DPV confirmation. Returns a single character.
+  // The possible values for DPV confirmation. Returns a single 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.
   string dpv_confirmation = 4;
 
   // The footnotes from delivery point validation.
@@ -90,11 +93,12 @@ message UspsData {
   // * `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 address
@@ -103,6 +107,8 @@ message UspsData {
   // * `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
   string dpv_footnote = 5;
 
   // Indicates if the address is a CMRA (Commercial Mail Receiving Agency)--a
@@ -127,6 +133,93 @@ message UspsData {
   // * `N`: The address is active
   string dpv_no_stat = 8;
 
+  // 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.
+  int32 dpv_no_stat_reason_code = 29;
+
+  // 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.
+  string dpv_drop = 30;
+
+  // 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.
+  string dpv_throwback = 31;
+
+  // 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.
+  string dpv_non_delivery_days = 32;
+
+  // 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
+  int32 dpv_non_delivery_days_values = 33;
+
+  // 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.
+  string dpv_no_secure_location = 34;
+
+  // 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.
+  string dpv_pbsa = 35;
+
+  // 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.
+  string dpv_door_not_accessible = 36;
+
+  // 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.
+  string dpv_enhanced_delivery_code = 37;
+
   // The carrier route code.
   // A four character code consisting of a one letter prefix and a three digit
   // route designator.