此页面由 Cloud Translation API 翻译。

自动补全（新）

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

自动补全（新）服务可以匹配输入内容的完整字词和子字符串，从而解析地点名称、地址和 Plus Codes。因此，应用可以在用户输入内容时发送查询，从而即时提供地点和查询预测。

Autocomplete（新）API 的响应可以包含两种类型的预测：

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

例如，您使用包含部分用户输入的字符串“Sicilian piz”作为输入调用 API，搜索区域限定为加利福尼亚州旧金山。然后，响应会包含与搜索字符串和搜索区域（例如名为“西西里披萨厨房”的餐厅）匹配的地点预测列表，以及关于该地点的详细信息。

返回的地点预测结果旨在呈现给用户，以帮助他们选择所需的地点。您可以发出地点详情（新）请求，以获取有关返回的任何地点预测结果的更多信息。

响应还可包含与搜索字符串和搜索区域匹配的查询预测列表，例如“西西里披萨和意大利面”。响应中的每个查询预测都包含 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

关于响应

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

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

注意：自动补全（新）总共会返回五项预测结果，其形式为 placePredictions 和/或 queryPredictions，具体取决于请求。例如，如果请求未设置 includeQueryPredictions，则响应正文最多包含五个 placePredictions。如果请求设置了 includeQueryPredictions，则响应正文最多可包含 placePredictions 和 queryPredictions 组合的五个预测结果。

完整的 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。自动补全（新）服务会根据此字符串返回候选匹配项，并按照其判断的相关性对结果进行排序。

可选参数

includedPrimaryTypes

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

默认情况下，无论地点关联的主要类型值如何，API 都会根据 input 参数返回所有地点。通过传递 includedPrimaryTypes 参数，将结果限制为特定主要类型或主要类型。

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

此参数还可能包含 (regions) 或 (cities) 中的一个。(regions) 类型的集合用于过滤区域或行政区划单位，例如社区和邮政编码。(cities) 类型的集合用于过滤 Google 标识为城市的地点。

如果出现以下情况，请求会被拒绝并返回 INVALID_REQUEST 错误：
- 指定了超过五种类型。
- 除了 (cities) 或 (regions) 之外，还可以指定任何类型。
- 指定了任何无法识别的类型。
注意：includedPrimaryTypes 参数仅适用于地点的主要类型，不适用于与地点关联的所有类型。虽然每个地点都有主要类型，但 Places API 并非支持所有主要类型（新）。支持的类型包括表 A 或表 B 中列出的类型。
includeQueryPredictions

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

仅包含指定区域列表中的结果，以最多包含 15 个 ccTLD（“顶级域名”）双字符值的数组指定。如果省略，则不会对响应应用任何限制。例如，要将区域限制为德国和法国：
```
    "includedRegionCodes": ["de", "fr"]
```
如果您同时指定 locationRestriction 和 includedRegionCodes，结果将位于这两项设置的交集区域中。
inputOffset

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

注意：在初始非公开预览版中，此属性称为 predictionTermOffset。
languageCode

返回结果时使用的首选语言。如果 input 中使用的语言与 languageCode 指定的值不同，或者返回的地点没有从当地语言翻译成 languageCode，那么结果可能采用混合语言。
- 您必须使用 IETF BCP-47 语言代码指定首选语言。
- 如果未提供 languageCode，则 API 会使用 Accept-Language 标头中指定的值。如果二者均未指定，则默认值为 en。如果您指定的语言代码无效，API 会返回 INVALID_ARGUMENT 错误。
- 首选语言对 API 选择返回的结果集以及返回顺序的影响微乎其微。这还会影响 API 更正拼写错误的能力。
- 该 API 会尝试提供用户和本地人口都能够读取的街道地址，同时反映用户输入。地点预测结果的格式因每个请求中的用户输入而异。
  - 首先，使用与 languageCode 参数所指示的语言偏好设置（如有）一致的名称（如果有）选择 input 参数中的匹配字词，否则使用最符合用户输入的名称。
  - 只有在选择匹配字词与 input 参数中的字词匹配之后，街道地址才会以当地语言进行格式设置，并采用用户可以读懂的脚本格式。
  - 选择匹配字词与 input 参数中的字词匹配后，所有其他地址均以首选语言返回。如果某个名称在首选语言中没有对应项，则 API 会使用最接近的匹配项。
locationBias 或 locationRestriction

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

注意：如果您同时省略 locationBias 和 locationRestriction，则 API 会默认使用 IP 自定义调整。通过 IP 自定义调整，API 会根据设备的 IP 地址来自定义调整结果。
- locationBias
  
  指定要搜索的区域。此位置充当偏差，这意味着可以返回指定位置周围的结果，包括指定区域以外的结果。
- locationRestriction
  
  指定要搜索的区域。系统不会返回指定区域以外的结果。
将 locationBias 或 locationRestriction 区域指定为矩形视口或圆形。
- 圆形由中心点和半径（以米为单位）定义。半径必须介于 0.0 和 50000.0 之间（含 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”（特指“大不列颠及北爱尔兰联合王国”）。

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

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

自动补全（新）示例

使用 locationRestriction 和 locationBias

默认情况下，该 API 使用 IP 自定义调整来控制搜索区域。通过 IP 自定义调整，API 使用设备的 IP 地址来自定义调整结果。您可以选择使用 locationRestriction 或 locationBias，但不能同时使用这两者，以指定要搜索的区域。

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

curl -X POST -d '{
  "input": "Amoeba",
  "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/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",
          "store",
          "point_of_interest",
          "electronics_store"
        ]
      }
    }
  ]
}

使用 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

现在，结果包含更多项，其中包括 5000 米半径范围之外的结果：

{
  "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"
        ]
      }
    },
    ...
  ]
}

使用 includePrimaryTypes

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

在以下示例中，您要指定 input 字符串“Soccer”，并使用 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 字段，该字段包含建议的文本搜索字符串。您可以发出文本搜索（新）请求，以获取有关任何返回的查询预测的更多信息。

注意：设置 includedRegionCodes 参数后，系统不会返回查询预测结果。

使用来源

在此示例中，请在请求中包含 origin 作为纬度和经度坐标。如果您添加了 origin，API 会在响应中包含 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
      }
    }
  ]
}

试试看！

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

选择页面右侧的 API 图标。
（可选）展开显示标准参数，并将 fields 参数设置为字段掩码。
（可选）修改请求正文。
选择执行按钮。在弹出式窗口中，选择您要用于提出请求的帐号。
在 API Explorer 面板中，选择展开图标以展开 API Explorer 窗口。

自动补全（新）

“自动补全（新）”请求

关于响应

必需参数

输入

可选参数

includedPrimaryTypes

includeQueryPredictions

includedRegionCodes

inputOffset

languageCode

locationBias 或 locationRestriction

locationBias

locationRestriction

发迹地

regionCode

sessionToken

自动补全（新）示例

使用 locationRestriction 和 locationBias

使用 includePrimaryTypes

请求查询预测

使用来源

试试看！