此页面由 Cloud Translation API 翻译。

自动补全（新）

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

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

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

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

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

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

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

“自动补全（新）”请求

“自动补全（新）”请求是对格式如下的网址的 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

使用自动补全功能发出请求（新功能）

Places API 支持现有的 Autocomplete API 和 Query Autocomplete API。如果您熟悉这些 API，可以参阅 Google 自动补全的预览版（新）将做出以下更改：

新版自动补全功能使用 HTTP POST 请求。将参数作为 HTTP POST 请求的一部分在请求正文或标头中传递。与现有 API 相比，您可以使用 HTTP GET 请求传递网址参数。
新的自动补全功能支持将 API 密钥和 OAuth 令牌作为身份验证机制。
新版自动补全功能仅支持 JSON 作为响应格式。

下表列出了现有 Autocomplete API 和 Query Autocomplete API 中已针对新的 Autocomplete 重命名或修改的参数，或不再支持的参数。

当前参数	新增参数	备注
`components`	`includedRegionCodes`
`language`	`languageCode`
`location`	`locationBias`
`ipbias`		如果同时省略 `locationBias` 和 `locationRestriction`，则 API 会默认使用 IP 自定义调整。
`offset`	`inputOffset`
`radius`	`locationBias` 或 `locationRestriction`
`region`	`regionCode`
`stricbounds`	`locationRestriction`
`sessiontoken`	`sessionToken`
`types`	`includedPrimaryTypes`

用量限额

在预览版期间，每个项目每分钟最多可以执行 600 次查询。

预览版的支持选项

虽然 Google 没有义务为服务的预览版提供支持服务，但我们会根据具体情况考虑这些开发阶段提出的请求。

预发布版本不在 Google Maps Platform 服务等级协议 (SLA) 的涵盖范围内。
建议使用回退机制，尤其是在生产环境中使用预发布版本时。回退情况的一些示例包括：超出配额、意外响应代码和延迟，或与现有自动补全功能相比时出现意外响应。

您可以使用问题跟踪器请求新功能或建议修改现有功能。请描述您希望添加的具体功能，以及您认为有必要添加该功能的理由。如果可以，请详细具体地说明您的用例以及该功能可带来哪些新机遇：

如果您对地图项还有其他疑问，请发送电子邮件至 newplacesapi@google.com。

关于响应

自动补全（新）会返回 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 中的最多五个类型值。地点必须与要包含在响应中的指定主要类型值之一匹配。

如果出现以下情况，请求会被拒绝并返回 INVALID_REQUEST 错误：
- 指定了超过五种类型。
- 指定了任何无法识别的类型。
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 中所列。您可以指定最多包含五个值的数组。如果省略，则返回所有类型。

在以下示例中，您要指定 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
      }
    }
  ]
}

自动补全（新）

“自动补全（新）”请求

使用自动补全功能发出请求（新功能）

用量限额

预览版的支持选项

关于响应

必需参数

输入

可选参数

includedPrimaryTypes

includeQueryPredictions

includedRegionCodes

inputOffset

languageCode

locationBias 或 locationRestriction

locationBias

locationRestriction

发迹地

regionCode

sessionToken

自动补全（新）示例

使用 locationRestriction 和 locationBias

使用 includePrimaryTypes

请求查询预测

使用来源