选择要返回的字段

欧洲经济区 (EEA) 开发者

发出地理编码请求时，您可以使用 字段掩码来指定要在响应中返回的字段列表。字段掩码可确保您不会请求不必要的数据，从而有助于缩短响应延迟时间。

对于“对地址进行地理编码”“对位置进行地理编码”和“地点地理编码”方法，系统默认会返回响应对象中的所有字段。虽然不是必需使用字段掩码，但我们强烈建议您使用，以缩短响应延迟时间。

定义响应字段掩码

响应字段掩码是以逗号分隔列表且不含空格的路径，其中每条路径都指定了响应对象中的一个唯一字段。路径从顶级响应字段开始，并使用以英文句点分隔的路径指向指定字段。

如需将响应字段掩码传递给请求，请使用网址参数 $fields 或 fields，或者使用 HTTP 或 gRPC 标头 X-Goog-FieldMask。

字段掩码示例

以下是正向地理编码请求的完整响应：

{
  "results": [
    {
      "place": "//places.googleapis.com/places/ChIJF4Yf2Ry7j4AR__1AkytDyAE",
      "placeId": "ChIJF4Yf2Ry7j4AR__1AkytDyAE",
      "location": {
        "latitude": 37.422010799999995,
        "longitude": -122.08474779999999
      },
      "granularity": "ROOFTOP",
      "viewport": {
        "low": {
          "latitude": 37.420656719708511,
          "longitude": -122.08547523029148
        },
        "high": {
          "latitude": 37.4233546802915,
          "longitude": -122.0827772697085
        }
      },
      "formattedAddress": "1600 Amphitheatre Pkwy, Mountain View, CA 94043, USA",
    ...
}

请使用响应字段的层次结构来构建字段掩码，格式如下：

topLevelField[.secondLevelField][.thirdLevelField][...]

例如，如需仅返回响应中的 placeId 字段，请使用以下字段掩码：

curl -X GET -H 'Content-Type: application/json' \
-H 'X-Goog-FieldMask: results.placeId' \
-H "X-Goog-Api-Key: API_KEY" \
https://geocode.googleapis.com/v4/geocode/address/1600+Amphitheatre+Parkway,+Mountain+View,+CA

响应现在为：

{
  "results": [
    {
      "placeId": "ChIJF4Yf2Ry7j4AR__1AkytDyAE"
    }
  ]
}

如需返回 viewport 字段，您的字段掩码为：

-H 'X-Goog-FieldMask: results.viewport'

响应现在为：

{
  "results": [
    {
      "viewport": {
        "low": {
          "latitude": 37.420654569708496,
          "longitude": -122.08547618029148
        },
        "high": {
          "latitude": 37.423352530291496,
          "longitude": -122.0827782197085
        }
      }
    }
  ]
}

如需同时返回这两个字段，请使用：

-H 'X-Goog-FieldMask: results.placeId,results.viewport'

响应现在为：

{
  "results": [
    {
      "placeId": "ChIJF4Yf2Ry7j4AR__1AkytDyAE",
      "viewport": {
        "low": {
          "latitude": 37.420654569708496,
          "longitude": -122.08547618029148
        },
        "high": {
          "latitude": 37.423352530291496,
          "longitude": -122.0827782197085
        }
      }
    }
  ]
}

gRPC 字段掩码

对于 gRPC，请设置一个包含响应字段掩码的变量。然后，您可以将该变量传递给请求。

const (
  fieldMask = "results.placeId,results.viewport"
)

字段路径注意事项

请仅添加响应中需要的字段，以便仅返回您需要的字段：

  • 缩短处理时间，以便以更低的 延迟时间返回结果。
  • 确保延迟时间性能稳定 。如果您选择所有字段，或者选择顶级的所有字段，则在添加新字段并自动将其添加到响应中时，您可能会遇到性能下降的情况。
  • 缩小响应大小，从而提高网络 吞吐量。

如需详细了解如何构建字段掩码，请参阅 field_mask.proto。