自动补全（新）

请选择平台： Android iOS JavaScript 网络服务
欧洲经济区 (EEA) 开发者

简介

自动补全（新）是一项 Web 服务，可针对 HTTP 请求返回地点预测结果和查询预测结果。在请求中，指定文本搜索字符串和用于控制搜索区域的地理边界。

自动补全（新）功能可以根据完整字词和输入的子字符串进行匹配，从而解析地点名称、地址和 Plus Codes。这样，应用就可以在用户输入内容时发送查询，从而即时进行地点和查询预测。

自动补全（新）的响应可以包含两种类型的预测：

  • 地点预测：根据指定的输入文本字符串和搜索区域预测地点，例如商家、地址和地图注点。默认情况下，系统会返回地点预测结果。
  • 查询预测：与输入文本字符串和搜索区域匹配的查询字符串。默认情况下，系统不会返回查询预测。使用 includeQueryPredictions 请求参数将查询预测添加到响应中。

例如，您调用“自动补全（新）”，并使用包含部分用户输入内容“Sicilian piz”的字符串作为输入，同时将搜索区域限制为加利福尼亚州旧金山。然后，响应会包含一个与搜索字符串和搜索区域匹配的地点预测结果列表，例如名为“Sicilian Pizza Kitchen”的餐厅，以及有关该地点的详细信息。

返回的地点预测结果旨在呈现给用户，以帮助他们选择所需地点。您可以发出地点详情（新）请求，以详细了解返回的任何地点预测结果。

响应还可以包含与搜索字符串和搜索区域匹配的查询预测结果列表，例如“西西里披萨和意面”。响应中的每个查询预测都包含 text 字段，其中包含建议的文本搜索字符串。使用该字符串作为文本搜索（新）的输入内容，以执行更详细的搜索。

借助 API Explorer，您可以发出实时请求，以便熟悉 API 和 API 选项：

自动补全（新）请求

自动补全（新）请求是指向以下格式的网址发出的 HTTP POST 请求：

https://places.googleapis.com/v1/places:autocomplete

在 JSON 请求正文或标头中传递所有参数，作为 POST 请求的一部分。 例如：

curl -X POST -d '{
  "input": "pizza",
  "locationBias": {
    "circle": {
      "center": {
        "latitude": 37.7937,
        "longitude": -122.3965
      },
      "radius": 500.0
    }
  }
}' \
-H 'Content-Type: application/json' -H "X-Goog-Api-Key: API_KEY" \
https://places.googleapis.com/v1/places:autocomplete

支持的参数

参数

说明

input*

要搜索的文本字符串（完整字词、子字符串、地点名称、地址、Plus Codes）。

FieldMask（HTTP 标头）

以英文逗号分隔的列表，用于指定要在响应中返回的字段。

includedPrimaryTypes

将结果限制为与最多五种指定主要类型之一相匹配的地点。

includePureServiceAreaBusinesses

如果为 true，则包括没有实体营业地点的商家（区域服务商家）。默认值为 false。

includeQueryPredictions

如果为 true，则在响应中同时包含地点预测和查询预测。默认值为 false。

includedRegionCodes

最多包含 15 个双字符国家/地区代码的数组，用于限制结果。

inputOffset

光标位置在输入字符串中的从零开始的 Unicode 字符偏移量，会影响预测。默认值为输入长度。

languageCode

结果的首选语言（IETF BCP-47 代码）。 默认为 Accept-Language 标头或“en”。

locationBias

指定一个区域（圆形或矩形），使搜索结果偏向于该区域，但允许该区域之外的结果。不能与 locationRestriction 一起使用。

locationRestriction

指定一个区域（圆形或矩形），以将搜索结果限制在该区域内。此区域以外的结果会被排除。 不能与 locationBias 一起使用。

origin

用于计算与预测目的地的直线距离 (distanceMeters) 的原点（纬度、经度）。

regionCode

用于设置响应格式和偏向建议的地区代码（例如，'uk'、'fr'）。

sessionToken

用户生成的字符串，用于将自动补全调用归入一个会话，以便进行结算。
* 表示必填字段。

关于响应

自动补全（新）功能会返回一个 JSON 对象作为响应。在回答中：

  • suggestions 数组包含所有预测的地点和查询，并按感知到的相关性排序。每个地点都由一个 placePrediction 字段表示，每个查询都由一个 queryPrediction 字段表示。
  • placePrediction 字段包含单个地点预测的详细信息，包括地点 ID 和文本说明。
  • queryPrediction 字段包含有关单个查询预测的详细信息。

完整的 JSON 对象采用以下格式：

{
  "suggestions": [
    {
      "placePrediction": {
        "place": "places/ChIJ5YQQf1GHhYARPKG7WLIaOko",
        "placeId": "ChIJ5YQQf1GHhYARPKG7WLIaOko",
        "text": {
          "text": "Amoeba Music, Haight Street, San Francisco, CA, USA",
          "matches": [
            {
              "endOffset": 6
            }]
        },
      ...
    },
    {
      "queryPrediction": {
        "text": {
          "text": "Amoeba Music",
          "matches": [
            {
              "endOffset": 6
            }]
        },
        ...
    }
  ...]
}

必需参数

  • 输入

    要搜索的文本字符串。指定完整字词和子字符串、地点名称、地址和 Plus Codes。 自动补全（新）服务将根据此字符串返回候选匹配结果，并按照其判断的相关性对结果进行排序。

可选参数

  • FieldMask

    通过创建响应字段掩码来指定要在响应中返回的字段列表。 使用 HTTP 标头 X-Goog-FieldMask 将响应字段掩码传递给方法。

    指定以英文逗号分隔的要返回的建议字段列表。例如，检索建议的 suggestions.placePrediction.text.text 和 suggestions.queryPrediction.text.text。

      X-Goog-FieldMask: suggestions.placePrediction.text.text,suggestions.queryPrediction.text.text

    使用 * 可检索所有字段。

      X-Goog-FieldMask: *

  • includedPrimaryTypes

    一个地点只能具有一种主要类型，该类型必须是表 A 或表 B 中列出的类型。例如，主要类型可能是 "mexican_restaurant" 或 "steak_house"。

    默认情况下，该 API 会根据 input 参数返回所有地点，而无需考虑与地点关联的主要类型值。通过传递 includedPrimaryTypes 参数，将结果限制为某种或某些主要类型。

    使用此参数可指定表 A 或表 B 中的最多五个类型值。地点必须与指定的主要类型值之一匹配，才能包含在响应中。

    此参数也可以改为包含 (regions) 或 (cities)。适用于区域或划分（例如社区和邮政编码）的 (regions) 类型集合过滤条件。(cities) 类型集合用于过滤 Google 识别为城市的地方。

    如果出现以下情况，请求会被拒绝并显示 INVALID_REQUEST 错误：

    • 指定了超过五种类型。
    • 除了 (cities) 或 (regions) 之外，还指定了其他类型。
    • 指定了任何无法识别的类型。

  • includePureServiceAreaBusinesses

    如果设置为 true，则响应中包含直接上门或为客户提供上门服务的商家，但不包含实体营业地点的商家。如果设置为 false，API 将仅返回具有实体营业地点的商家。

  • includeQueryPredictions

    如果值为 true，则响应会同时包含地点预测和查询预测。默认值为 false，表示响应仅包含地点预测。

  • includedRegionCodes

    仅包含指定地区列表中的结果，以数组形式指定，最多包含 15 个 ccTLD（“顶级域名”）双字符值。如果省略，则对响应不应用任何限制。例如，如需将区域限制为德国和法国，请执行以下操作：

        "includedRegionCodes": ["de", "fr"]

    如果您同时指定了 locationRestriction 和 includedRegionCodes，则结果位于这两个设置的交集区域。

  • inputOffset

    从零开始的 Unicode 字符偏移量，用于指示 input 中的光标位置。 光标位置可能会影响返回的预测结果。如果为空，则默认为 input 的长度。

  • languageCode

    返回结果的首选语言。如果 input 中使用的语言与 languageCode 指定的值不同，或者返回的地点没有从本地语言到 languageCode 的翻译，则结果可能采用混合语言。

    • 您必须使用 IETF BCP-47 语言代码来指定首选语言。
    • 如果未提供 languageCode，API 会使用 Accept-Language 标头中指定的值。如果两者均未指定，则默认值为 en。如果您指定的语言代码无效，则 API 会返回 INVALID_ARGUMENT 错误。
    • 首选语言对 API 选择返回的结果集以及返回结果的顺序有一定影响。 这还会影响 API 更正拼写错误的能力。
    • 该 API 会尝试提供用户和当地居民都能看懂的街道地址，同时反映用户输入的内容。地点预测的格式因每个请求中的用户输入而异。
      • 系统会先选择 input 参数中的匹配字词，并尽可能使用与 languageCode 参数指示的语言偏好设置一致的名称，否则会使用与用户输入最匹配的名称。
      • 街道地址以本地语言显示，并尽可能采用用户可读的文字，但前提是已选择匹配的字词来与 input 参数中的字词相匹配。
      • 其他所有地址均以首选语言返回，前提是已选择匹配的字词来与 input 参数中的字词相匹配。如果首选语言中没有相应名称，API 会使用最接近的匹配项。

  • locationBias 或 locationRestriction

    您可以指定 locationBias 或 locationRestriction（但不能同时指定这两者）来定义搜索区域。您可以将 locationRestriction 视为指定结果必须位于的区域，而将 locationBias 视为指定结果必须靠近但可以位于该区域之外的区域。

    • locationBias

      指定要搜索的区域。此位置用作偏差，这意味着可以返回指定位置附近的结果，包括指定区域之外的结果。

    • locationRestriction

      指定要搜索的区域。系统不会返回指定区域以外的结果。

    将 locationBias 或 locationRestriction 区域指定为矩形视口或圆形。

    • 圆由中心点和半径（以米为单位）定义。半径必须介于 0.0 和 50000.0 之间（含边界值）。默认值为 0.0。对于 locationRestriction，您必须将半径设置为大于 0.0 的值。否则，请求不会返回任何结果。

      例如：

      "locationBias": {
  "circle": {
    "center": {
      "latitude": 37.7937,
      "longitude": -122.3965
    },
    "radius": 500.0
  }
}

    • 矩形是纬度-经度视口，表示为两个对角相对的 low 和高点。视口被视为一个闭合区域，这意味着它包含其边界。纬度范围必须介于 -90 度到 90 度之间（含），经度范围必须介于 -180 度到 180 度之间（含）：

      • 如果 low = high，则视口由该单个点组成。
      • 如果 low.longitude > high.longitude，则经度范围会反转（视口跨越 180 度经度线）。
      • 如果 low.longitude = -180 度且 high.longitude = 180 度，则视口包含所有经度。
      • 如果 low.longitude = 180 度且 high.longitude = -180 度，则经度范围为空。

      low 和 high 都必须填充，并且所表示的框不能为空。空视口会导致错误。

      例如，此视口完全包含纽约市：

      "locationBias": {
  "rectangle": {
    "low": {
      "latitude": 40.477398,
      "longitude": -74.259087
    },
    "high": {
      "latitude": 40.91618,
      "longitude": -73.70018
    }
  }
}

  • 源

    用于计算到目的地（以 distanceMeters 形式返回）的直线距离的起点。如果省略此值，则不会返回直线距离。必须指定为纬度和经度坐标：

    "origin": {
    "latitude": 40.477398,
    "longitude": -74.259087
}

  • regionCode

    用于设置响应格式的地区代码，以 ccTLD（“顶级域名”）双字符值的形式指定。大多数 ccTLD 代码都与 ISO 3166-1 代码完全一致，但也有一些明显的例外情况。例如，英国的 ccTLD 为“uk”(.co.uk)，而其 ISO 3166-1 代码为“gb”（从技术上讲，是指“大不列颠及北爱尔兰联合王国”这一实体）。

    建议也会根据地区代码产生偏差。Google 建议根据用户的区域偏好设置 regionCode。

    如果您指定的区域代码无效，API 会返回 INVALID_ARGUMENT 错误。此参数可能会根据适用法律影响结果。

  • sessionToken

    会话令牌是用户生成的字符串，用于将“自动补全（新）”调用跟踪为“会话”。自动补全（新）使用会话令牌将用户自动补全搜索的查询和选择阶段归入不同的会话，以便进行结算。如需了解详情，请参阅会话令牌。

选择用于使结果产生偏差的参数

自动补全（新）参数可能会以不同的方式影响搜索结果。 下表根据预期结果提供了有关参数使用的建议。
参数 使用建议
regionCode 根据用户的区域偏好设置。
includedRegionCodes 设置为将结果限制为指定区域的列表。
locationBias 当用户偏好某个区域内或附近的结果时使用。如果适用，请将区域定义为用户正在查看的地图的视口。
locationRestriction 仅当不应返回区域外的结果时，才使用 only。
origin 当需要计算到每个预测值的直线距离时使用。

自动补全（新）示例

使用 locationRestriction 将搜索限制在某个区域内

locationRestriction 用于指定搜索区域。系统不会返回指定区域以外的结果。在以下示例中，您使用 locationRestriction 将请求限制为以旧金山为中心、半径为 5, 000 米的圆形：

curl -X POST -d '{
  "input": "Art museum",
  "locationRestriction": {
    "circle": {
      "center": {
        "latitude": 37.7749,
        "longitude": -122.4194
      },
      "radius": 5000.0
    }
  }
}' \
-H 'Content-Type: application/json' -H "X-Goog-Api-Key: API_KEY" \
https://places.googleapis.com/v1/places:autocomplete

指定区域内的所有结果都包含在 suggestions 数组中：

  {
    "suggestions": [
      {
        "placePrediction": {
          "place": "places/ChIJkQQVTZqAhYARHxPt2iJkm1Q",
          "placeId": "ChIJkQQVTZqAhYARHxPt2iJkm1Q",
          "text": {
            "text": "Asian Art Museum, Larkin Street, San Francisco, CA, USA",
            "matches": [
              {
                "startOffset": 6,
                "endOffset": 16
              }
            ]
          },
          "structuredFormat": {
            "mainText": {
              "text": "Asian Art Museum",
              "matches": [
                {
                  "startOffset": 6,
                  "endOffset": 16
                }
              ]
            },
            "secondaryText": {
              "text": "Larkin Street, San Francisco, CA, USA"
            }
          },
          "types": [
            "establishment",
            "museum",
            "point_of_interest"
          ]
        }
      },
      {
        "placePrediction": {
          "place": "places/ChIJI7NivpmAhYARSuRPlbbn_2w",
          "placeId": "ChIJI7NivpmAhYARSuRPlbbn_2w",
          "text": {
            "text": "de Young Museum, Hagiwara Tea Garden Drive, San Francisco, CA, USA",
            "matches": [
              {
                "endOffset": 15
              }
            ]
          },
          "structuredFormat": {
            "mainText": {
              "text": "de Young Museum",
              "matches": [
                {
                  "endOffset": 15
                }
              ]
            },
            "secondaryText": {
              "text": "Hagiwara Tea Garden Drive, San Francisco, CA, USA"
            }
          },
          "types": [
            "establishment",
            "point_of_interest",
            "tourist_attraction",
            "museum"
          ]
        }
      },
      /.../
    ]
  }

您还可以使用 locationRestriction 将搜索限制为仅在矩形视口中进行。以下示例将请求限制为旧金山市中心：

  curl -X POST -d '{
    "input": "Art museum",
    "locationRestriction": {
      "rectangle": {
        "low": {
          "latitude": 37.7751,
          "longitude": -122.4219
        },
        "high": {
          "latitude": 37.7955,
          "longitude": -122.3937
        }
      }
    }
  }' \
  -H 'Content-Type: application/json' -H "X-Goog-Api-Key: API_KEY" \
  https://places.googleapis.com/v1/places:autocomplete

结果包含在 suggestions 数组中：

  {
    "suggestions": [
      {
        "placePrediction": {
          "place": "places/ChIJkQQVTZqAhYARHxPt2iJkm1Q",
          "placeId": "ChIJkQQVTZqAhYARHxPt2iJkm1Q",
          "text": {
            "text": "Asian Art Museum, Larkin Street, San Francisco, CA, USA",
            "matches": [
              {
                "startOffset": 6,
                "endOffset": 16
              }
            ]
          },
          "structuredFormat": {
            "mainText": {
              "text": "Asian Art Museum",
              "matches": [
                {
                  "startOffset": 6,
                  "endOffset": 16
                }
              ]
            },
            "secondaryText": {
              "text": "Larkin Street, San Francisco, CA, USA"
            }
          },
          "types": [
            "point_of_interest",
            "museum",
            "establishment"
          ]
        }
      },
      {
        "placePrediction": {
          "place": "places/ChIJyQNK-4SAhYARO2DZaJleWRc",
          "placeId": "ChIJyQNK-4SAhYARO2DZaJleWRc",
          "text": {
            "text": "International Art Museum of America, Market Street, San Francisco, CA, USA",
            "matches": [
              {
                "startOffset": 14,
                "endOffset": 24
              }
            ]
          },
          "structuredFormat": {
            "mainText": {
              "text": "International Art Museum of America",
              "matches": [
                {
                  "startOffset": 14,
                  "endOffset": 24
                }
              ]
            },
            "secondaryText": {
              "text": "Market Street, San Francisco, CA, USA"
            }
          },
          "types": [
            "museum",
            "point_of_interest",
            "tourist_attraction",
            "art_gallery",
            "establishment"
          ]
        }
      }
    ]
  }

使用 locationBias 将搜索范围限定在某个区域

使用 locationBias 时，位置信息会作为一种偏向，这意味着系统可能会返回指定位置附近的结果，包括指定区域以外的结果。在以下示例中，您将请求偏向旧金山市中心：

curl -X POST -d '{
  "input": "Amoeba",
  "locationBias": {
    "circle": {
      "center": {
        "latitude": 37.7749,
        "longitude": -122.4194
      },
      "radius": 5000.0
    }
  }
}' \
-H 'Content-Type: application/json' -H "X-Goog-Api-Key: API_KEY" \
https://places.googleapis.com/v1/places:autocomplete

现在，结果中包含的商品数量更多了，包括 5, 000 米半径范围之外的结果：

{
  "suggestions": [
    {
      "placePrediction": {
        "place": "places/ChIJ5YQQf1GHhYARPKG7WLIaOko",
        "placeId": "ChIJ5YQQf1GHhYARPKG7WLIaOko",
        "text": {
          "text": "Amoeba Music, Haight Street, San Francisco, CA, USA",
          "matches": [
            {
              "endOffset": 6
            }
          ]
        },
        "structuredFormat": {
          "mainText": {
            "text": "Amoeba Music",
            "matches": [
              {
                "endOffset": 6
              }
            ]
          },
          "secondaryText": {
            "text": "Haight Street, San Francisco, CA, USA"
          }
        },
        "types": [
          "electronics_store",
          "point_of_interest",
          "store",
          "establishment",
          "home_goods_store"
        ]
      }
    },
    {
      "placePrediction": {
        "place": "places/ChIJr7uwwy58hYARBY-e7-QVwqw",
        "placeId": "ChIJr7uwwy58hYARBY-e7-QVwqw",
        "text": {
          "text": "Amoeba Music, Telegraph Avenue, Berkeley, CA, USA",
          "matches": [
            {
              "endOffset": 6
            }
          ]
        },
        "structuredFormat": {
          "mainText": {
            "text": "Amoeba Music",
            "matches": [
              {
                "endOffset": 6
              }
            ]
          },
          "secondaryText": {
            "text": "Telegraph Avenue, Berkeley, CA, USA"
          }
        },
        "types": [
          "electronics_store",
          "point_of_interest",
          "establishment",
          "home_goods_store",
          "store"
        ]
      }
    },
    ...
  ]
}

您还可以使用 locationBias 将搜索结果偏向于矩形视口。以下示例将请求限制为旧金山市中心：

  curl -X POST -d '{
    "input": "Amoeba",
    "locationBias": {
      "rectangle": {
        "low": {
          "latitude": 37.7751,
          "longitude": -122.4219
        },
        "high": {
          "latitude": 37.7955,
          "longitude": -122.3937
        }
      }
    }
  }' \
  -H 'Content-Type: application/json' -H "X-Goog-Api-Key: API_KEY" \
  https://places.googleapis.com/v1/places:autocomplete

虽然矩形视口内的搜索结果会显示在响应中，但由于存在偏差，部分结果位于定义的边界之外。结果也包含在 suggestions 数组中：

  {
    "suggestions": [
      {
        "placePrediction": {
          "place": "places/ChIJ5YQQf1GHhYARPKG7WLIaOko",
          "placeId": "ChIJ5YQQf1GHhYARPKG7WLIaOko",
          "text": {
            "text": "Amoeba Music, Haight Street, San Francisco, CA, USA",
            "matches": [
              {
                "endOffset": 6
              }
            ]
          },
          "structuredFormat": {
            "mainText": {
              "text": "Amoeba Music",
              "matches": [
                {
                  "endOffset": 6
                }
              ]
            },
            "secondaryText": {
              "text": "Haight Street, San Francisco, CA, USA"
            }
          },
          "types": [
            "point_of_interest",
            "store",
            "establishment"
          ]
        }
      },
      {
        "placePrediction": {
          "place": "places/ChIJr7uwwy58hYARBY-e7-QVwqw",
          "placeId": "ChIJr7uwwy58hYARBY-e7-QVwqw",
          "text": {
            "text": "Amoeba Music, Telegraph Avenue, Berkeley, CA, USA",
            "matches": [
              {
                "endOffset": 6
              }
            ]
          },
          "structuredFormat": {
            "mainText": {
              "text": "Amoeba Music",
              "matches": [
                {
                  "endOffset": 6
                }
              ]
            },
            "secondaryText": {
              "text": "Telegraph Avenue, Berkeley, CA, USA"
            }
          },
          "types": [
            "point_of_interest",
            "store",
            "establishment"
          ]
        }
      },
      {
        "placePrediction": {
          "place": "places/ChIJRdmfADq_woARYaVhnfQSUTI",
          "placeId": "ChIJRdmfADq_woARYaVhnfQSUTI",
          "text": {
            "text": "Amoeba Music, Hollywood Boulevard, Los Angeles, CA, USA",
            "matches": [
              {
                "endOffset": 6
              }
            ]
          },
          "structuredFormat": {
            "mainText": {
              "text": "Amoeba Music",
              "matches": [
                {
                  "endOffset": 6
                }
              ]
            },
            "secondaryText": {
              "text": "Hollywood Boulevard, Los Angeles, CA, USA"
            }
          },
          "types": [
            "point_of_interest",
            "store",
            "establishment"
          ]
        }
      },
    /.../
    ]
  }

使用 includedPrimaryTypes

使用 includedPrimaryTypes 参数可指定表 A、表 B 中的最多五个类型值，或者仅指定 (regions) 或仅指定 (cities)。地点必须与指定的主要类型值之一匹配，才能包含在响应中。

在以下示例中，您指定了“足球”的 input 字符串，并使用 includedPrimaryTypes 参数将结果限制为 "sporting_goods_store" 类型的场所：

curl -X POST -d '{
  "input": "Soccer",
  "includedPrimaryTypes": ["sporting_goods_store"],
  "locationBias": {
    "circle": {
      "center": {
        "latitude": 37.7749,
        "longitude": -122.4194
      },
      "radius": 500.0
    }
  }
}' \
-H 'Content-Type: application/json' -H "X-Goog-Api-Key: API_KEY" \
https://places.googleapis.com/v1/places:autocomplete

如果您省略 includedPrimaryTypes 参数，则结果可能会包含您不想要的类型的商家，例如 "athletic_field"。

请求查询预测

默认情况下，系统不会返回查询预测。使用 includeQueryPredictions 请求参数向响应添加查询预测。例如：

curl -X POST -d '{
  "input": "Amoeba",
  "includeQueryPredictions": true,
  "locationBias": {
    "circle": {
      "center": {
        "latitude": 37.7749,
        "longitude": -122.4194
      },
      "radius": 5000.0
    }
  }
}' \
-H 'Content-Type: application/json' -H "X-Goog-Api-Key: API_KEY" \
https://places.googleapis.com/v1/places:autocomplete

suggestions 数组现在包含地点预测和查询预测，如上文关于响应中所述。每个查询预测都包含 text 字段，其中包含建议的文本搜索字符串。您可以发出文本搜索（新）请求，以获取有关任何返回的查询预测的更多信息。

使用来源

在此示例中，将 origin 作为纬度和经度坐标包含在请求中。如果您添加 origin，自动补全（新）会在响应中添加 distanceMeters 字段，其中包含从 origin 到目的地的直线距离。此示例将原点设置为旧金山的中心：

curl -X POST -d '{
  "input": "Amoeba",
  "origin": {
    "latitude": 37.7749,
    "longitude": -122.4194
  },
  "locationRestriction": {
    "circle": {
      "center": {
        "latitude": 37.7749,
        "longitude": -122.4194
      },
      "radius": 5000.0
    }
  }
}' \
-H 'Content-Type: application/json' -H "X-Goog-Api-Key: API_KEY" \
https://places.googleapis.com/v1/places:autocomplete

响应现在包含 distanceMeters：

{
  "suggestions": [
    {
      "placePrediction": {
        "place": "places/ChIJ5YQQf1GHhYARPKG7WLIaOko",
        "placeId": "ChIJ5YQQf1GHhYARPKG7WLIaOko",
        "text": {
          "text": "Amoeba Music, Haight Street, San Francisco, CA, USA",
          "matches": [
            {
              "endOffset": 6
            }
          ]
        },
        "structuredFormat": {
          "mainText": {
            "text": "Amoeba Music",
            "matches": [
              {
                "endOffset": 6
              }
            ]
          },
          "secondaryText": {
            "text": "Haight Street, San Francisco, CA, USA"
          }
        },
        "types": [
          "home_goods_store",
          "establishment",
          "point_of_interest",
          "store",
          "electronics_store"
        ],
        "distanceMeters": 3012
      }
    }
  ]
}

响应中缺少距离

在某些情况下，即使请求中包含 origin，响应正文中也会缺少 distanceMeters。这种情况可能发生在以下场景中：

  • distanceMeters 不包含在 route 预测中。
  • 如果 distanceMeters 的值为 0，则不会包含该值。当预测位置与提供的 origin 位置之间的距离小于 1 米时，就会出现这种情况。

尝试从已解析的对象中读取 distanceMeters 字段的客户端库将返回一个值为 0 的字段。为避免误导用户，请不要向用户显示距离为零。

试试看！

借助 API Explorer，您可以发出示例请求，以便熟悉 API 和 API 选项。

  1. 选择页面右侧的 API 图标 api。

  2. （可选）修改请求参数。

  3. 选择执行按钮。在对话框中，选择您要用于提出请求的账号。

  4. 在 APIs Explorer 面板中，选择全屏图标 全屏 以展开 APIs Explorer 窗口。