切换账号后Google Maps地址验证接口uspsData缺失standardizedAddress字段

问题概况 #

使用Python的Google Maps地址验证库时，此前调用接口返回的uspsData字段包含standardizedAddress数据，但切换账号后，该字段仅返回carrierRoute。相关封装类代码如下：

class Gmaps:
    ctype_map = {
        'street_number': 'line1', 'route': 'line1',
        'postal_code': 'zip_code', 'postal_code_suffix': 'zip_code',
        'locality': 'city', 'administrative_area_level_1': 'state',
        'country': 'country', 'subpremise': 'line2',
    }
    all_states  = {y for x in Address.state_map.items() for y in x}
    def __init__(self, raw=False):
        self.raw = raw
        self.gmaps = googlemaps.Client(creds['gmaps_key'])

    def validate(self, line1='', city='', state='', zip_code='', line2='', country='US', usps=False):
        if usps and country != 'US':
            raise Exception('USPS validation only works for US addresses')
        envelope_lines = [
            f'{line1} {line2}',
            f'{city}, {state} {zip_code}'
        ]
        try:
            result = self.gmaps.addressvalidation(envelope_lines, country, city, enableUspsCass=True)
        except Exception as e:
            raise e

排查方向及解决方案 #

1. 账号权限与产品启用检查 #

• 确认新账号已启用Google Maps Address Validation API，且开通了USPS CASS认证对应的权限。enableUspsCass=True参数需要账号具备USPS验证权限，否则仅会返回基础的carrierRoute字段。
• 检查账号计费状态：若存在欠费或配额耗尽，接口可能会限制返回字段范围。

2. 接口参数调用校验 #

• 核对addressvalidation方法的参数是否符合最新要求：当前代码中envelope_lines的拼接逻辑是否合理，是否遗漏了必要参数（如是否需要明确指定返回字段集合）。
• 测试时可临时打印完整返回结果，排查是否存在权限提示或错误信息：

  try:
      result = self.gmaps.addressvalidation(envelope_lines, country, city, enableUspsCass=True)
      print("完整接口返回:", result)  # 打印完整结果定位问题
  except Exception as e:
      raise e
  

3. 接口版本变更确认 #

查看Google Maps Address Validation API的更新日志，确认是否存在字段返回逻辑的调整，是否需要修改请求参数或方式来获取standardizedAddress。

官方文档UspsAddress部分翻译 #

UspsAddress类型代表经USPS CASS认证标准化后的地址信息，包含以下字段：

• standardizedAddress：符合USPS格式的标准化地址，涵盖街道、城市、州、邮编等详细内容；
• carrierRoute：USPS投递路线编码，用于邮件分拣；
• deliveryPoint：投递点信息，包含投递点编码及校验位；
• footnotes：USPS返回的备注信息，说明地址验证状态（如是否为商业/住宅地址等）。

注意：仅当请求开启enableUspsCass=true且账号具备对应权限时，才会返回完整的UspsAddress字段。若权限不足或地址无法通过USPS验证，部分字段可能不会返回。

内容的提问来源于stack exchange，提问作者gnarlyninja