地点详情(新)

获得地点 ID 后,您可以通过发起地点详情(新)请求来请求有关特定场所或地图注点的更多详细信息。“地点详情(新)”请求会返回有关指定地点的更全面信息,如完整地址、电话号码、用户评分和评价。

获取地点 ID 的方式有多种。您可以使用:

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

试试吧!

“地点详情(新)”请求

“地点详情”请求是一个 HTTP GET 请求,格式如下:

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

将所有参数作为网址参数传递,或作为 GET 请求的一部分在标头中传递。例如:

https://places.googleapis.com/v1/places/ChIJj61dQgK6j4AR4GeTYWZsKWw?fields=id,displayName&key=API_KEY

或者在 c网址 命令中:

curl -X GET -H 'Content-Type: application/json' \
-H "X-Goog-Api-Key: API_KEY" \
-H "X-Goog-FieldMask: id,displayName" \
https://places.googleapis.com/v1/places/ChIJj61dQgK6j4AR4GeTYWZsKWw

“地点详情(新)”响应

地点详情(新)会返回 JSON 对象作为响应。在响应中:

  • 响应由 Place 对象表示。Place 对象包含有关地点的详细信息。
  • 请求中传递的 FieldMask 指定了 Place 对象中返回的字段列表。

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

{
  "name": "places/ChIJkR8FdQNB0VQRm64T_lv1g1g",
  "id": "ChIJkR8FdQNB0VQRm64T_lv1g1g",
  "displayName": {
    "text": "Trinidad"
  }
  ...
}

必需参数

  • FieldMask

    通过创建响应字段掩码,指定要在响应中返回的字段列表。使用网址参数 $fieldsfields,或者使用 HTTP 标头 X-Goog-FieldMask 将响应字段掩码传递给该方法。响应中没有默认的返回字段列表。 如果省略字段掩码,则该方法会返回错误。

    字段遮盖是一种很好的设计做法,可确保您不会请求不必要的数据,这有助于避免不必要的处理时间和结算费用。

    指定要返回的地点数据类型的逗号分隔列表。例如,用于检索地点的显示名称和地址。

    X-Goog-FieldMask: displayName,formattedAddress

    使用 * 检索所有字段。

    X-Goog-FieldMask: *

    指定以下一个或多个字段:

    • 以下字段会触发地点详情(仅 ID)SKU

      idname*photos

      *name 字段包含地点资源名称,格式为:places/PLACE_ID使用 displayName 访问地点的文本名称。

    • 以下字段会触发地点详情(仅限位置)SKU

      addressComponentsadrFormatAddressformattedAddresslocationplusCodeshortFormattedAddresstypesviewport

    • 以下字段会触发地点详情(基本)SKU

      accessibilityOptionsbusinessStatusdisplayNamegoogleMapsUriiconBackgroundColoriconMaskBaseUriprimaryTypeprimaryTypeDisplayNamesubDestinationsutcOffsetMinutes

    • 以下字段会触发地点详情(高级)SKU

      currentOpeningHourscurrentSecondaryOpeningHoursinternationalPhoneNumbernationalPhoneNumberpriceLevelratingregularOpeningHoursregularSecondaryOpeningHoursuserRatingCountwebsiteUri

    • 以下字段会触发地点详情(首选)SKU

      allowsDogscurbsidePickupdeliverydineIneditorialSummaryevChargeOptionsfuelOptionsgoodForChildrengoodForGroupsgoodForWatchingSportsliveMusicmenuForChildrenparkingOptionspaymentOptionsoutdoorSeatingreservablerestroomdelivery、 {2 / }、 delivery {2 / } {2 / } {2 / } {2 / } {2 / { 2 / } { 2 / } { 2 / } { 2 / } { 2 / } { 2 / } { 2 / } { 2 / } { 2 / } { 2 / } { 2reviewsservesBeerservesBreakfastservesBrunchservesCocktailsservesCoffeeservesDessertsservesDinnerservesLunchservesVegetarianFoodservesWinetakeout

  • placeId

    用于唯一标识地点的文本标识符,从文本搜索(新)附近搜索(新)返回。 如需详细了解地点 ID,请参阅地点 ID 概览

    字符串 places/PLACE_ID 也称为地点资源名称。在“地点详情(新)”“附近搜索(新)”和“文本搜索(新)”请求的响应中,此字符串包含在响应的 name 字段中。独立地点 ID 包含在响应的 id 字段中。

可选参数

  • languageCode

    返回结果时使用的语言。

    • 请参阅支持的语言列表。Google 会经常更新支持的语言,因此该列表可能并不详尽。
    • 如果未提供 languageCode,则 API 默认为 en。如果您指定的语言代码无效,API 将返回 INVALID_ARGUMENT 错误。
    • 该 API 会尽力提供用户和当地人都能看懂的街道地址。为实现这一目标,它会返回当地语言的街道地址,如有必要,可将其音译为可由用户阅读的文字,同时遵循首选语言。所有其他地址均以首选语言返回。地址组成部分均以同一语言返回,该语言是从第一个组成部分中选择的语言。
    • 如果某个名称在首选语言中没有对应项,则 API 会使用最接近的匹配项。
    • 首选语言对 API 选择返回的结果集以及返回顺序的影响微乎其微。地理编码器会根据语言以不同的方式解读缩写,例如街道类型的缩写,或者使用一种语言有效但在另一种语言中无效的同义词。
  • regionCode

    用于设置响应格式的地区代码,以 双字符 CLDR 代码值的形式指定。没有默认值。

    如果响应中 formattedAddress 字段的国家/地区名称与 regionCode 匹配,则 formattedAddress 中省略国家/地区代码。此参数不会影响 adrFormatAddress(始终包含国家/地区名称)或 shortFormattedAddress(一律不包含国家/地区名称)。

    除了某些明显的例外情况之外,大多数 CLDR 代码都与 ISO 3166-1 代码相同。例如,英国的 ccTLD 为“uk”(.co.uk),而其 ISO 3166-1 代码为“gb”(专指“大不列颠及北爱尔兰联合王国”)。 该参数可能会影响根据适用法律的结果。

  • sessionToken

    会话令牌是用户生成的字符串,用于将自动补全(新)调用作为“会话”进行跟踪。自动补全(新)使用会话令牌将用户自动补全搜索的查询和地点选择阶段归入不同的会话,以便进行结算。会话令牌会传递到“自动补全(新)”调用之后的“地点详情(新)”调用中。如需了解详情,请参阅会话令牌

地点详情示例

下例通过 placeId 请求地点详情:

curl -X GET -H 'Content-Type: application/json' \
-H "X-Goog-Api-Key: API_KEY" \
-H "X-Goog-FieldMask: id,displayName" \
https://places.googleapis.com/v1/places/ChIJj61dQgK6j4AR4GeTYWZsKWw

请注意,X-Goog-FieldMask 标头指定响应包含以下数据字段:id,displayName。然后,响应将采用以下格式:

{
  "id": "ChIJj61dQgK6j4AR4GeTYWZsKWw",
  "displayName": {
    "text": "Googleplex",
    "languageCode": "en"
  }
}

向字段掩码添加更多数据类型,以返回其他信息。例如,添加 formattedAddress,plusCode 以在响应中包含地址和 Plus Code

curl -X GET -H 'Content-Type: application/json' \
-H "X-Goog-Api-Key: API_KEY" \
-H "X-Goog-FieldMask: id,displayName,formattedAddress,plusCode" \
https://places.googleapis.com/v1/places/ChIJj61dQgK6j4AR4GeTYWZsKWw

现在,响应格式为:

{
  "id": "ChIJj61dQgK6j4AR4GeTYWZsKWw",
  "formattedAddress": "1600 Amphitheatre Pkwy, Mountain View, CA 94043, USA",
  "plusCode": {
    "globalCode": "849VCWC7+RW",
    "compoundCode": "CWC7+RW Mountain View, CA, USA"
  },
  "displayName": {
    "text": "Googleplex",
    "languageCode": "en"
  }
}

试试看!

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

如需发出请求,请执行以下操作:

  1. (可选)将 name 参数设置为:
    places/PLACE_ID
  2. (可选)展开显示标准参数,并将 fields 参数设置为字段掩码
  3. 选择执行按钮。在弹出式窗口中,选择您要用于发出请求的帐号。