Google People API返回用户国家的时机及country字段填充场景咨询

嘿，我来帮你理清这两个关于Google People API的问题，结合实际开发中的经验给你解答：

1. Google People API何时会返回用户的国家信息？ #

要让API返回用户的国家信息，得同时满足三个条件：

• 用户账号里有已填写的国家数据：这个信息来自用户在Google个人资料（比如「关于我」页面的联系地址、个人信息板块）里主动填写的内容。如果用户从来没填过国家相关信息，API肯定不会返回。
• 请求时指定了正确的字段：调用people.get或people.connections.list这类接口时，必须在personFields参数里包含addresses字段（国家信息嵌套在addresses数组里）。举个例子，请求参数要写成personFields=addresses，如果还要获取其他字段，用逗号分隔就行，比如personFields=names,addresses。
• 拥有足够的权限：你需要获取能读取用户地址信息的权限，比如https://www.googleapis.com/auth/contacts.readonly（针对联系人数据）或者https://www.googleapis.com/auth/userinfo.profile（针对当前用户的个人资料）。权限不够的话，就算有数据也会被过滤掉。

2. 哪些场景下country和country_code字段会被填充？ #

你遇到的返回结果只有formattedValue和formattedType的情况，是因为API返回的是非结构化的地址字符串，而country和country_code属于结构化字段，只有满足以下场景才会被填充：

• 用户填写了结构化地址：当用户在Google个人资料里添加地址时，不是直接输入一整段文本，而是通过Google提供的结构化表单（比如分开填写街道、城市，尤其是通过下拉选择器选中国家），Google会把这些信息结构化存储，API返回时就会带上country（国家名称）和country_code（ISO标准代码，比如US、CN）。
• 地址文本被成功解析为结构化数据：如果用户输入的是一段格式标准的完整地址（比如「上海市浦东新区XX路2号，中国」），Google的地址解析引擎能从中识别出明确的国家信息，这时候API也会提取并填充这两个字段。
• 反过来，如果用户输入的地址模糊不清（比如只写了「欧洲」），或者地址文本无法被Google解析出明确的国家，API就只会返回formattedValue（完整地址文本）和formattedType（地址类型，比如「home」「work」），不会填充结构化的国家字段。

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