选择要返回的字段

欧洲经济区 (EEA) 开发者

如果您的账单邮寄地址在欧洲经济区，自 2025 年 7 月 8 日起，您在使用服务时需遵守 Google Maps Platform 欧洲经济区服务条款。具体功能因区域而异。 了解详情。

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

对于基本地理编码方法（对地址进行地理编码、对位置进行地理编码和地点地理编码），默认情况下会返回响应对象中的所有字段，这与搜索目的地不同，后者需要指定字段掩码。虽然基本方法不需要字段掩码，但我们强烈建议您使用字段掩码来减少响应延迟时间。

重要提示： 使用搜索目的地方法时，您必须指定字段掩码。

定义响应字段掩码

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

注意： 字段路径列表中的任何位置都不能使用空格。

通过使用网址参数 $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][...]

注意： 对于 GeocodeAddress、GeocodeLocation 和 GeocodePlace 方法，请求默认返回响应对象中的所有字段（相当于指定 * 的字段掩码）。对于 SearchDestinations 方法，必须指定字段掩码；省略字段掩码会导致错误。

搜索目标字段掩码

调用 SearchDestinations 时，请指定所需的确切目的地属性，例如主要地点详情、入口、导航点、建筑物轮廓 (displayPolygon) 和地标：

curl -X POST -d '{"addressQuery": {"addressQuery": "1600 Amphitheatre Pkwy, Mountain View, CA"}}' \
-H 'Content-Type: application/json' \
-H 'X-Goog-FieldMask: destinations.primary.displayName,destinations.primary.displayPolygon,destinations.entrances,destinations.navigationPoints,destinations.landmarks' \
-H "X-Goog-Api-Key: API_KEY" \
https://geocode.googleapis.com/v4/geocode/destinations

核心地理编码字段掩码

例如，如需在 GeocodeAddress 响应中仅返回 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。